project-mgr 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.0 - 2026-10-28
+
+### Added
+
+- Add independent Todos with optional project/source links, per-item completion, cancellation, reopening, and CLI commands.
+- Create Todos atomically from new next steps and explicitly convert legacy steps without rewriting history.
+- Add dashboard activity completion controls and project-filtered Todo views.
+- Preserve Todo state in version-3 exports and enforce same-origin local JSON writes.
+
+### Changed
+
+- Guide agents to ask before recording multiple sub-projects, either under one project name or with snapshot tags.
+- Sync the Chinese README with CLI help, activity completion, and Todo documentation.
+
+## 0.3.2 - 2026-10-16
+
+- Add general and per-command CLI help, no-argument help, and package version aliases without opening the database.
+
 ## 0.3.1 - 2026-10-16
 
 ### Changed

package/README.md

@@ -127,6 +127,20 @@ Delete `/tmp/project-mgr-manual-test.sqlite` when it is no longer needed.
 
 Automated tests use an in-memory database or SQLite files in the system temporary directory; they do not read or write the default database. `PMGR_DB_PATH=:memory:` also works for one command, but each CLI command runs in a separate process and its data disappears when the command exits, so it is not suitable for consecutive manual tests.
 
+## CLI help and version
+
+```bash
+pmgr                    # Show general help
+pmgr -h                 # Also: --help or help
+pmgr add --help          # Command usage and available options
+pmgr help history       # Equivalent to history -h
+pmgr -v                 # Also: -V, --version, or version
+```
+
+Help and version commands exit successfully without opening or creating a database.
+Version output comes from the installed package metadata. The compatible
+`pmgr status <command> --help` form is also supported.
+
 ## Quick start
 
 Append a project status:
@@ -319,3 +333,25 @@ Activity cards display Completed with a follow-up link and retain original detai
 Export now emits a version-2 bundle `{ "version": 2, "entries": [...], "completions": [...] }`. JSONL emits one complete bundle per line. Entries retain UUIDs and recording times; events retain UUIDs and per-target predecessor links, including revocations. Import accepts legacy entry objects/arrays/JSONL and version-2 bundles, checks identity conflicts, and applies each file atomically. Re-importing the same bundle is idempotent. Event order is significant: import events in exported order; divergent histories fail instead of silently merging. Older clients cannot import version-2 bundles. Migration adds UUIDs to existing snapshots without changing their content.
 
 Independently migrated copies of legacy data receive different UUIDs. Cross-import may fail on an existing `externalRef`; no implicit identity adoption occurs. Restore a bundle into a fresh database for a faithful migration. Older writers are rejected if they omit UUIDs. With an existing `externalRef`, `add` retains its existing snapshot and applies explicitly supplied `--completes` links to that snapshot; identical active links are no-ops. Use `complete` to make after-the-fact reconciliation explicit.
+
+### Todos and dashboard actions
+
+New `add --next` values create independent Todos linked to the new activity.
+Historical next steps stay as text until explicitly converted in the dashboard.
+The Todos tab supports standalone creation, optional project assignment, source
+links, completion, cancellation, and reopening. Project cards filter this list.
+Activity cards provide **Mark completed**, recording a follow-up with the current
+project status; this neither completes the project nor its Todos.
+
+```sh
+pmgr todo-add --title "Review results" --project demo --json
+pmgr todo-add --title "Unassigned idea" --json
+pmgr todos --project demo --json
+pmgr todo-update --uid <todo-uuid> --status completed --json
+```
+
+Exports with Todos use version 3 and preserve their identities and state;
+version-2 and legacy imports remain supported without creating new Todos from
+old next-step text. Conflicting Todo snapshots are rejected atomically on import.
+Dashboard writes are restricted to same-origin localhost requests with JSON bodies;
+remote-host dashboards remain read-only.

package/README_CN.md

@@ -127,6 +127,18 @@ pnpm start history --project test-project
 
 自动化测试会使用内存数据库或系统临时目录中的 SQLite 文件，不会读写默认数据库。`PMGR_DB_PATH=:memory:` 也可用于单条命令，但每个 CLI 命令都是独立进程，命令结束后数据就会消失，不适合连续手工测试。
 
+## CLI 帮助与版本
+
+```bash
+pmgr                    # 显示通用帮助
+pmgr -h                 # 也可使用 --help 或 help
+pmgr add --help          # 命令用法与可用选项
+pmgr help history       # 等价于 history -h
+pmgr -v                 # 也可使用 -V、--version 或 version
+```
+
+帮助与版本命令会成功退出，且不会打开或创建数据库。版本输出来自已安装包的元数据。也支持兼容形式 `pmgr status <command> --help`。
+
 ## 快速开始
 
 追加一条项目状态：
@@ -186,7 +198,7 @@ pnpm start at \
 - `--external-ref`：全局幂等键。重复写入同一项目时返回原记录；若被其他项目占用则报错。
 - `--json`：输出稳定 JSON。
 
-## 项目元数据与模糊查询
+### 项目元数据与模糊查询
 
 可通过 `set-project` 设置或更新项目的名称、简介与备注，或使用 `--clear-description` / `--clear-notes` 清空：
 
@@ -298,3 +310,44 @@ pnpm build
 ```
 
 Statements、branches、functions、lines 的覆盖率门槛均为 100%。详细设计见[架构文档](docs/architecture.md)。
+
+## 补全更早的动态
+
+项目状态和动态是否完成是两回事。关联条目前，先查看 `pmgr history --project demo --json`。`status` 是原始快照；`effectiveStatus` 计入显式的后续完成；`isCurrent` 标识该项目的最新快照。缺少 `completedBy` 并不表示这条动态尚未完成。
+
+```bash
+# 一次更新可完成多条更早的记录（本地数字 ID 或可移植 UUID）。
+pmgr add --project demo --status active --summary "部署已验收" \
+  --completes 12 --completes 15 --source agent --json
+# 关联一条已有的后续记录，或不删除历史地纠正错误关联。
+pmgr complete --entry 12 --by 18 --source agent --json
+pmgr revoke-completion --entry 12 --by 18 --reason "验收仍未完成" --source agent --json
+```
+
+只关联那些全部未完成工作（包括阻塞和下一步）都已解决的条目。同一项目内的关联要求后续记录的发生时间严格更晚；发生时间相同的关联会被拒绝。每个目标只能有一个有效的完成来源。重复同一关联是空操作；要替换时需先撤销。`add --completes` 会原子写入快照、元数据和关联。已有历史不会自动对账。
+
+动态卡片会显示已完成，并链到后续动态；原始详情保留在可展开的「原始记录」中。「当前状态」和「已有后续更新」只表示快照新旧，与是否完成相互独立。`/api/entries/<id-or-uid>` 和 `/?entry=<uid>` 即使不在初始动态页，也能打开一条记录。日期筛选选择的是快照；完成标注反映的是当前结果。`at` 仍然返回不含完成信息的历史项目快照；按历史时点查询完成状态暂不支持。
+
+导出现在会输出 version 2 包 `{ "version": 2, "entries": [...], "completions": [...] }`。JSONL 每行输出一个完整包。条目保留 UUID 和记录时间；事件保留 UUID，以及每个目标的前驱链接（含撤销）。导入同时接受旧版条目对象、数组、JSONL 和 version 2 包，会检查身份冲突，并按文件原子应用。重复导入同一包是幂等的。事件顺序有意义：须按导出顺序导入；历史不一致时导入失败，不会静默合并。旧客户端无法导入 version 2 包。迁移会给已有快照补上 UUID，不改变其内容。
+
+各自独立迁移的旧数据副本会得到不同的 UUID。跨库导入可能因已存在的 `externalRef` 失败，不会隐式沿用对方身份。要忠实迁移，请把包恢复到一个全新数据库。省略 UUID 的旧写入会被拒绝。若 `externalRef` 已存在，`add` 会保留原快照，并把显式传入的 `--completes` 关联应用到该快照；相同且仍然有效的关联是空操作。事后补关联请使用 `complete`，让对账显式发生。
+
+### 待办与仪表板操作
+
+新的 `add --next` 会创建独立待办，并关联到这条新动态。
+历史中的下一步仍只是文本，直到在仪表板里显式转为待办。
+待办页支持单独创建、可选关联项目、查看来源动态、标为已完成、取消和重新打开。项目卡片可以筛选这份列表。
+动态卡片提供 **标为已完成**，会用当前项目状态记一条后续动态；这既不会把项目标成完成，也不会完成它的待办。
+
+```sh
+pmgr todo-add --title "复查结果" --project demo --json
+pmgr todo-add --title "未归属的想法" --json
+pmgr todos --project demo --json
+pmgr todo-update --uid <todo-uuid> --status completed --json
+```
+
+带待办的导出使用 version 3，并保留待办的身份与状态；
+version 2 和旧版导入仍然可用，且不会把旧的下一步文本自动变成新待办。
+冲突的待办快照会在导入时整批拒绝。
+仪表板写入仅接受同源的 localhost JSON 请求；
+绑定到远程主机时，仪表板保持只读。

package/dist/cli.js

@@ -2,23 +2,33 @@
 import { readFileSync, realpathSync } from "node:fs";
 import { basename } from "node:path";
 import { pathToFileURL } from "node:url";
-import { addStatus, at, current, history, importLedger, exportLedger, changeCompletion, listProjects, openLedger, parseTime, setProjectMetadata, startServer, ValidationError, } from "./index.js";
+import { addStatus, createTodo, listTodos, updateTodo, at, current, history, importLedger, exportLedger, changeCompletion, listProjects, openLedger, parseTime, setProjectMetadata, startServer, ValidationError, } from "./index.js";
+const booleanFlags = new Set([
+    "json",
+    "clear-description",
+    "clear-notes",
+    "open",
+    "no-open",
+    "help",
+    "version",
+]);
 const repeats = new Set(["next", "blocker", "decision", "tag", "completes"]);
 function parse(argv) {
     const command = [];
     const flags = Object.create(null);
     for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
+        const raw = argv[index];
+        const token = raw === "-h"
+            ? "--help"
+            : raw === "-v" || raw === "-V"
+                ? "--version"
+                : raw;
         if (!token.startsWith("--")) {
             command.push(token);
             continue;
         }
         const key = token.slice(2);
-        if (key === "json" ||
-            key === "clear-description" ||
-            key === "clear-notes" ||
-            key === "open" ||
-            key === "no-open") {
+        if (booleanFlags.has(key)) {
             if (flags[key] !== undefined)
                 throw new ValidationError(`--${key} may only be supplied once`);
             flags[key] = true;
@@ -57,6 +67,9 @@ const allowedFlags = new Map([
             "json",
         ]),
     ],
+    ["todo-add", new Set(["title", "project", "entry", "json"])],
+    ["todos", new Set(["project", "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"])],
     ["import", new Set(["file", "json"])],
@@ -83,6 +96,87 @@ const allowedFlags = new Map([
     ["export", new Set(["project", "format"])],
     ["serve", new Set(["port", "host", "open", "no-open", "json"])],
 ]);
+const commandHelp = {
+    "todo-add": [
+        "Create an independent or linked Todo",
+        "--title <text> [--project <name>] [--entry <uid>] [--json]",
+    ],
+    todos: ["List Todos", "[--project <name>] [--json]"],
+    "todo-update": [
+        "Change Todo status or assign a project",
+        "--uid <uuid> [--status open|completed|cancelled] [--project <name>] [--json]",
+    ],
+    add: [
+        "Append a status snapshot",
+        "--project <name> --summary <text> [options]",
+    ],
+    complete: [
+        "Link a completed activity to its follow-up",
+        "--entry <id-or-uid> --by <id-or-uid> [options]",
+    ],
+    "revoke-completion": [
+        "Revoke an activity completion link",
+        "--entry <id-or-uid> --by <id-or-uid> [options]",
+    ],
+    import: [
+        "Import a JSON or JSONL ledger",
+        "<file> [--json] | --file <path> [--json]",
+    ],
+    current: [
+        "Show the latest status of each project",
+        "[--project <name>] [--json]",
+    ],
+    projects: ["List or search projects", "[--query <text>] [--json]"],
+    list: ["Alias for projects", "[--query <text>] [--json]"],
+    "set-project": ["Update project metadata", "--project <name> [options]"],
+    history: [
+        "Show status history, newest first",
+        "[--project <name>] [options]",
+    ],
+    at: [
+        "Show a project's status at a time",
+        "--project <name> --at <ISO-timestamp> [--json]",
+    ],
+    export: [
+        "Export a portable ledger",
+        "[--project <name>] [--format json|jsonl]",
+    ],
+    serve: [
+        "Start the local web dashboard",
+        "[--port <number>] [--host <address>] [--no-open] [--json]",
+    ],
+};
+function help(action) {
+    if (action) {
+        const [description, usage] = commandHelp[action];
+        const options = [...allowedFlags.get(action)].map((key) => `  --${key}${booleanFlags.has(key) ? "" : " <value>"}${repeats.has(key) ? " (repeatable)" : ""}`);
+        return `Usage: pmgr ${action} ${usage}\n\n${description}\n\nOptions:\n${options.join("\n")}\n  -h, --help  Show this help\n`;
+    }
+    return `Usage: pmgr <command> [options]
+       pmgr status <command> [options]
+
+Local-first, append-only project status ledger.
+
+Commands:
+${Object.entries(commandHelp)
+        .map(([name, [description]]) => `  ${name.padEnd(20)}${description}`)
+        .join("\n")}
+  help [command]      Show general or command help
+  version             Show the installed package version
+
+Options:
+  -h, --help          Show help (also supported after a command)
+  -v, -V, --version   Show the installed package version
+
+Environment:
+  PMGR_DB_PATH        SQLite path (default: ~/.local/share/project-mgr/project-mgr.sqlite)
+
+Examples:
+  pmgr current --json
+  pmgr add --project demo --status active --summary "Work started"
+  pmgr help history
+`;
+}
 function validateInvocation(command, flags) {
     const statusCommand = command[0] === "status";
     const action = command[statusCommand ? 1 : 0];
@@ -182,11 +276,54 @@ function imported(file) {
 }
 export function run(argv, write = process.stdout.write.bind(process.stdout)) {
     const { command, flags } = parse(argv);
+    if (command[0] === "help") {
+        command.shift();
+        flags.help = true;
+    }
+    if (argv.length === 0 || flags.help === true) {
+        delete flags.help;
+        const action = command.length || Object.keys(flags).length
+            ? validateInvocation(command, flags)
+            : undefined;
+        write(help(action));
+        return;
+    }
+    if (flags.version === true || command[0] === "version") {
+        if (Object.keys(flags).some((key) => key !== "version") ||
+            (command.length > 0 && (command.length !== 1 || command[0] !== "version")))
+            throw new ValidationError("usage: pmgr --version (or: pmgr version)");
+        const metadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        write(`${metadata.version}\n`);
+        return;
+    }
     const action = validateInvocation(command, flags);
     const db = openLedger();
     const json = flags.json === true;
     try {
         switch (action) {
+            case "todo-add":
+                output(createTodo(db, {
+                    title: stringFlag(flags, "title", true),
+                    project: stringFlag(flags, "project"),
+                    entryUid: stringFlag(flags, "entry"),
+                }), json, write);
+                break;
+            case "todos": {
+                const todos = listTodos(db, stringFlag(flags, "project"));
+                if (json)
+                    output(todos, true, write);
+                else
+                    write(todos
+                        .map((t) => `${t.uid}\t${t.status}\t${t.project ?? "-"}\t${t.title}`)
+                        .join("\n") + "\n");
+                break;
+            }
+            case "todo-update":
+                output(updateTodo(db, stringFlag(flags, "uid", true), {
+                    status: stringFlag(flags, "status"),
+                    project: stringFlag(flags, "project"),
+                }), json, write);
+                break;
             case "add": {
                 const project = stringFlag(flags, "project", true);
                 const description = stringFlag(flags, "description");

package/dist/db.d.ts

@@ -36,11 +36,13 @@ export type CompletionEvent = {
 export declare function getEntry(db: Ledger, ref: string): StatusEntry | undefined;
 export declare function changeCompletion(db: Ledger, targetRef: string, byRef: string, action?: CompletionEvent["action"], reason?: string, source?: Source): CompletionEvent;
 export declare function exportLedger(db: Ledger, project?: string): {
+    todos?: Todo[] | undefined;
     version: number;
     entries: {
         recordedAt: string;
         progress?: string | undefined;
         externalRef?: string | undefined;
+        nextStepsSourceUid?: string | undefined;
         uid: string;
         project: string;
         status: import("./domain.js").ProjectStatus;
@@ -55,3 +57,18 @@ export declare function exportLedger(db: Ledger, project?: string): {
     completions: CompletionEvent[];
 };
 export declare function importLedger(db: Ledger, values: unknown[]): InsertResult[];
+export type Todo = {
+    uid: string;
+    title: string;
+    project: string | null;
+    entryUid: string | null;
+    stepIndex: number | null;
+    status: "open" | "completed" | "cancelled";
+    createdAt: string;
+    completedAt: string | null;
+};
+export declare function listTodos(db: Ledger, project?: string): Todo[];
+export declare function createTodo(db: Ledger, value: unknown): Todo;
+export declare function convertNextStep(db: Ledger, ref: string, index: number): Todo;
+export declare function updateTodo(db: Ledger, uid: string, value: unknown): Todo;
+export declare function completeActivity(db: Ledger, ref: string): StatusEntry;

package/dist/db.js

@@ -75,6 +75,19 @@ export function openLedger(path = databasePath()) {
         BEGIN SELECT RAISE(ABORT, 'entry uid required; upgrade the writer'); END;`);
             db.prepare("INSERT INTO schema_migrations(version) VALUES (3)").run();
         }
+        if (!db.prepare("SELECT 1 FROM schema_migrations WHERE version = 4").get()) {
+            db.exec(`ALTER TABLE status_entries ADD COLUMN next_steps_source_uid TEXT REFERENCES status_entries(uid);
+        CREATE TABLE todos (
+        uid TEXT PRIMARY KEY, title TEXT NOT NULL,
+        project TEXT REFERENCES projects(slug),
+        entry_uid TEXT REFERENCES status_entries(uid),
+        step_index INTEGER, status TEXT NOT NULL CHECK(status IN ('open','completed','cancelled')),
+        created_at TEXT NOT NULL, completed_at TEXT,
+        UNIQUE(entry_uid, step_index)
+      );
+      CREATE INDEX idx_todos_project ON todos(project);
+      INSERT INTO schema_migrations(version) VALUES (4);`);
+        }
     }).immediate();
     return db;
 }
@@ -88,6 +101,9 @@ function entryFromRow(row) {
         ...(row.progress ? { progress: row.progress } : {}),
         blockers: JSON.parse(row.blockers_json),
         nextSteps: JSON.parse(row.next_steps_json),
+        ...(row.next_steps_source_uid
+            ? { nextStepsSourceUid: row.next_steps_source_uid }
+            : {}),
         decisions: JSON.parse(row.decisions_json),
         tags: JSON.parse(row.tags_json),
         occurredAt: row.occurred_at,
@@ -204,6 +220,8 @@ export function addStatus(db, value, defaultSource = "human", completes = []) {
     return db
         .transaction(() => {
         const result = addValidatedStatus(db, input);
+        if (result.inserted && !result.entry.nextStepsSourceUid)
+            result.entry.nextSteps.forEach((_, index) => convertNextStep(db, result.entry.uid, index));
         for (const target of completes)
             changeCompletion(db, target, result.entry.uid, "complete", undefined, input.source);
         return result;
@@ -235,15 +253,24 @@ function addValidatedStatus(db, input, recordedAt) {
             return { entry: existing, inserted: false };
         }
     }
+    if (input.nextStepsSourceUid) {
+        const origin = getEntry(db, input.nextStepsSourceUid);
+        if (!origin ||
+            origin.nextStepsSourceUid !== undefined ||
+            origin.project !== input.project ||
+            origin.occurredAt >= input.occurredAt ||
+            !isDeepStrictEqual(origin.nextSteps, input.nextSteps))
+            throw new ValidationError("invalid next step provenance");
+    }
     const now = recordedAt ?? new Date().toISOString();
     upsertProjectMetadata(db, { project: input.project });
     const project = db
         .prepare("SELECT id FROM projects WHERE slug = ?")
         .get(input.project);
     const result = db
-        .prepare(`INSERT INTO status_entries(project_id, status, summary, progress, blockers_json, next_steps_json, decisions_json, tags_json, occurred_at, recorded_at, source, external_ref, uid)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(project.id, input.status, input.summary, input.progress ?? null, JSON.stringify(input.blockers), JSON.stringify(input.nextSteps), JSON.stringify(input.decisions), JSON.stringify(input.tags), input.occurredAt, now, input.source, input.externalRef ?? null, input.uid ?? randomUUID());
+        .prepare(`INSERT INTO status_entries(project_id, status, summary, progress, blockers_json, next_steps_json, decisions_json, tags_json, occurred_at, recorded_at, source, external_ref, uid, next_steps_source_uid)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(project.id, input.status, input.summary, input.progress ?? null, JSON.stringify(input.blockers), JSON.stringify(input.nextSteps), JSON.stringify(input.decisions), JSON.stringify(input.tags), input.occurredAt, now, input.source, input.externalRef ?? null, input.uid ?? randomUUID(), input.nextStepsSourceUid ?? null);
     return {
         entry: one(db, `${select} WHERE e.id = ?`, result.lastInsertRowid),
         inserted: true,
@@ -423,7 +450,17 @@ export function exportLedger(db, project) {
         const rows = db
             .prepare(`SELECT c.* FROM completion_events c JOIN status_entries e ON e.uid = c.target_uid JOIN projects p ON p.id = e.project_id ${project ? "WHERE p.slug = ?" : ""} ORDER BY c.id`)
             .all(...(project ? [project] : []));
-        return { version: 2, entries, completions: rows.map(completionFromRow) };
+        const todos = listTodos(db, project);
+        return {
+            version: todos.length || entries.some((entry) => entry.nextStepsSourceUid)
+                ? 3
+                : 2,
+            entries,
+            completions: rows.map(completionFromRow),
+            ...(todos.length || entries.some((entry) => entry.nextStepsSourceUid)
+                ? { todos }
+                : {}),
+        };
     })();
 }
 function record(value, keys) {
@@ -475,8 +512,15 @@ export function importLedger(db, values) {
         const results = [];
         for (const value of values) {
             if (value && typeof value === "object" && "version" in value) {
-                const bundle = record(value, ["version", "entries", "completions"]);
-                if (bundle.version !== 2 ||
+                const bundle = record(value, [
+                    "version",
+                    "entries",
+                    "completions",
+                    "todos",
+                ]);
+                if ((bundle.version !== 2 && bundle.version !== 3) ||
+                    (bundle.version === 3 && !Array.isArray(bundle.todos)) ||
+                    (bundle.version === 2 && bundle.todos !== undefined) ||
                     !Array.isArray(bundle.entries) ||
                     !Array.isArray(bundle.completions))
                     throw new ValidationError("invalid ledger bundle");
@@ -489,6 +533,9 @@ export function importLedger(db, values) {
                 }
                 for (const event of bundle.completions)
                     insertCompletion(db, validateCompletionEvent(event));
+                if (bundle.version === 3)
+                    for (const todo of bundle.todos)
+                        importTodo(db, todo);
             }
             else
                 results.push(addValidatedStatus(db, validateStatusEntry(value, "import")));
@@ -497,3 +544,188 @@ export function importLedger(db, values) {
     })
         .immediate();
 }
+const todoSelect = `SELECT uid, title, project, entry_uid AS entryUid,
+  step_index AS stepIndex, status, created_at AS createdAt, completed_at AS completedAt FROM todos`;
+export function listTodos(db, project) {
+    return db
+        .prepare(todoSelect +
+        (project ? " WHERE project = ?" : "") +
+        " ORDER BY created_at, uid")
+        .all(...(project ? [project] : []));
+}
+function insertTodo(db, todo) {
+    db.prepare(`INSERT INTO todos(uid,title,project,entry_uid,step_index,status,created_at,completed_at)
+    VALUES (?,?,?,?,?,?,?,?)`).run(todo.uid, todo.title, todo.project, todo.entryUid, todo.stepIndex, todo.status, todo.createdAt, todo.completedAt);
+    return todo;
+}
+export function createTodo(db, value) {
+    const input = record(value, ["title", "project", "entryUid"]);
+    if (typeof input.title !== "string" ||
+        !input.title.trim() ||
+        input.title.trim().length > 2000)
+        throw new ValidationError("title must contain 1 to 2000 characters");
+    let project = null;
+    let entryUid = null;
+    if (input.project != null) {
+        project = validateProjectMetadataInput({ project: input.project }).project;
+        if (!db.prepare("SELECT 1 FROM projects WHERE slug = ?").get(project))
+            throw new ValidationError("project not found");
+    }
+    if (input.entryUid != null) {
+        const entry = getEntry(db, validateUid(input.entryUid));
+        if (!entry)
+            throw new ValidationError("entry not found");
+        if (project && project !== entry.project)
+            throw new ValidationError("source project mismatch");
+        project = entry.project;
+        entryUid = entry.uid;
+    }
+    return insertTodo(db, {
+        uid: randomUUID(),
+        title: input.title.trim(),
+        project,
+        entryUid,
+        stepIndex: null,
+        status: "open",
+        createdAt: new Date().toISOString(),
+        completedAt: null,
+    });
+}
+export function convertNextStep(db, ref, index) {
+    return db
+        .transaction(() => {
+        const entry = getEntry(db, ref);
+        if (!entry ||
+            !Number.isInteger(index) ||
+            index < 0 ||
+            index >= entry.nextSteps.length)
+            throw new ValidationError("next step not found");
+        if (entry.nextStepsSourceUid)
+            return convertNextStep(db, entry.nextStepsSourceUid, index);
+        const existing = db
+            .prepare(todoSelect + " WHERE entry_uid = ? AND step_index = ?")
+            .get(entry.uid, index);
+        if (existing)
+            return existing;
+        return insertTodo(db, {
+            uid: randomUUID(),
+            title: entry.nextSteps[index],
+            project: entry.project,
+            entryUid: entry.uid,
+            stepIndex: index,
+            status: "open",
+            createdAt: new Date().toISOString(),
+            completedAt: null,
+        });
+    })
+        .immediate();
+}
+export function updateTodo(db, uid, value) {
+    validateUid(uid);
+    const input = record(value, ["status", "project"]);
+    return db
+        .transaction(() => {
+        const todo = db.prepare(todoSelect + " WHERE uid = ?").get(uid);
+        if (!todo)
+            throw new ValidationError("todo not found");
+        if (input.status !== undefined) {
+            if (!["open", "completed", "cancelled"].includes(input.status))
+                throw new ValidationError("invalid todo status");
+            if (todo.status !== input.status) {
+                todo.status = input.status;
+                todo.completedAt =
+                    todo.status === "completed" ? new Date().toISOString() : null;
+            }
+        }
+        if (input.project !== undefined) {
+            if (todo.entryUid)
+                throw new ValidationError("source-linked todo project cannot change");
+            todo.project =
+                input.project === null
+                    ? null
+                    : validateProjectMetadataInput({ project: input.project }).project;
+            if (todo.project &&
+                !db.prepare("SELECT 1 FROM projects WHERE slug = ?").get(todo.project))
+                throw new ValidationError("project not found");
+        }
+        db.prepare("UPDATE todos SET status=?, completed_at=?, project=? WHERE uid=?").run(todo.status, todo.completedAt, todo.project, uid);
+        return todo;
+    })
+        .immediate();
+}
+function importTodo(db, value) {
+    const input = record(value, [
+        "uid",
+        "title",
+        "project",
+        "entryUid",
+        "stepIndex",
+        "status",
+        "createdAt",
+        "completedAt",
+    ]);
+    validateUid(input.uid);
+    if (typeof input.title !== "string" ||
+        !input.title.trim() ||
+        input.title.length > 2000)
+        throw new ValidationError("invalid todo title");
+    if (!["open", "completed", "cancelled"].includes(input.status))
+        throw new ValidationError("invalid todo status");
+    parseTime(input.createdAt, "createdAt");
+    if (input.status === "completed")
+        parseTime(input.completedAt, "completedAt");
+    else if (input.completedAt !== null)
+        throw new ValidationError("invalid completion timestamp");
+    if (input.project !== null) {
+        validateProjectMetadataInput({ project: input.project });
+        upsertProjectMetadata(db, { project: input.project });
+    }
+    if (input.entryUid !== null) {
+        const entry = getEntry(db, validateUid(input.entryUid));
+        if (!entry || entry.project !== input.project)
+            throw new ValidationError("invalid todo source");
+        if (input.stepIndex !== null &&
+            (!Number.isInteger(input.stepIndex) ||
+                Number(input.stepIndex) < 0 ||
+                entry.nextSteps[Number(input.stepIndex)] !== input.title))
+            throw new ValidationError("invalid next step index");
+    }
+    else if (input.stepIndex !== null)
+        throw new ValidationError("next step requires a source");
+    const todo = input;
+    const existing = db.prepare(todoSelect + " WHERE uid = ?").get(todo.uid);
+    if (existing) {
+        if (!isDeepStrictEqual(existing, todo))
+            throw new ValidationError("conflicting todo uid");
+    }
+    else
+        insertTodo(db, todo);
+}
+export function completeActivity(db, ref) {
+    return db
+        .transaction(() => {
+        const entry = getEntry(db, ref);
+        if (!entry)
+            throw new ValidationError("entry not found");
+        if (entry.effectiveStatus === "completed")
+            return entry;
+        const latest = current(db, entry.project)[0];
+        const occurredAt = new Date(Math.max(Date.now(), Date.parse(latest.occurredAt) + 1)).toISOString();
+        // Preserve current context without generating another set of next-step Todos.
+        const followUp = addValidatedStatus(db, validateStatusEntry({
+            project: entry.project,
+            status: latest.status,
+            summary: `Completed activity #${entry.id}`,
+            progress: latest.progress,
+            blockers: latest.blockers,
+            nextSteps: latest.nextSteps,
+            nextStepsSourceUid: latest.nextStepsSourceUid ?? latest.uid,
+            decisions: latest.decisions,
+            tags: latest.tags,
+            occurredAt,
+        }));
+        changeCompletion(db, entry.uid, followUp.entry.uid);
+        return getEntry(db, entry.uid);
+    })
+        .immediate();
+}

package/dist/domain.d.ts

@@ -26,13 +26,15 @@ export type StatusEntryInput = {
     progress?: string;
     blockers?: string[];
     nextSteps?: string[];
+    nextStepsSourceUid?: string;
     decisions?: string[];
     tags?: string[];
     occurredAt?: string;
     source?: Source;
     externalRef?: string;
 };
-export type StatusEntry = Required<Omit<StatusEntryInput, "progress" | "externalRef">> & {
+export type StatusEntry = Required<Omit<StatusEntryInput, "progress" | "externalRef" | "nextStepsSourceUid">> & {
+    nextStepsSourceUid?: string;
     id: number;
     progress?: string;
     externalRef?: string;

package/dist/domain.js

@@ -16,6 +16,7 @@ const keys = new Set([
     "progress",
     "blockers",
     "nextSteps",
+    "nextStepsSourceUid",
     "decisions",
     "tags",
     "occurredAt",
@@ -128,6 +129,9 @@ export function validateStatusEntry(value, defaultSource = "human") {
         progress: text(input.progress, "progress"),
         blockers: textList(input.blockers, "blockers"),
         nextSteps: textList(input.nextSteps, "nextSteps"),
+        ...(input.nextStepsSourceUid === undefined
+            ? {}
+            : { nextStepsSourceUid: validateUid(input.nextStepsSourceUid) }),
         decisions: textList(input.decisions, "decisions"),
         tags: textList(input.tags, "tags"),
         occurredAt: input.occurredAt === undefined
@@ -150,6 +154,8 @@ export function toPortableStatusEntry(entry) {
         occurredAt: entry.occurredAt,
         source: entry.source,
     };
+    if (entry.nextStepsSourceUid !== undefined)
+        result.nextStepsSourceUid = entry.nextStepsSourceUid;
     if (entry.progress !== undefined)
         result.progress = entry.progress;
     if (entry.externalRef !== undefined)

package/dist/server.js

@@ -1,7 +1,8 @@
 import { exec } from "node:child_process";
 import { createServer, } from "node:http";
 import { URL } from "node:url";
-import { countEntries, getEntry, history, listProjects, openLedger, } from "./db.js";
+import { countEntries, createTodo, listTodos, updateTodo, convertNextStep, completeActivity, getEntry, history, listProjects, openLedger, } from "./db.js";
+import { ValidationError } from "./domain.js";
 import { getWebUIHTML } from "./web/ui.js";
 export function openBrowser(url) {
     const platform = process.platform;
@@ -34,6 +35,11 @@ function sendJson(res, statusCode, data) {
     res.end(JSON.stringify(data));
 }
 export function handleRequest(req, res, db) {
+    if (req.method === "POST" &&
+        /^\/api\/(todos(?:\/[^/]+)?|entries\/[^/]+\/(complete|todos))$/.test((req.url || "").split("?")[0])) {
+        void handleMutation(req, res, db);
+        return;
+    }
     if (req.method !== "GET" && req.method !== "HEAD") {
         sendJson(res, 405, { error: "Method not allowed" });
         return;
@@ -61,6 +67,10 @@ export function handleRequest(req, res, db) {
         res.end(getWebUIHTML());
         return;
     }
+    if (pathname === "/api/todos") {
+        sendJson(res, 200, listTodos(db, query.project));
+        return;
+    }
     if (pathname === "/api/projects") {
         const projects = listProjects(db, { query: query.query });
         sendJson(res, 200, projects);
@@ -162,3 +172,68 @@ export function startServer(options = {}) {
         });
     });
 }
+async function handleMutation(req, res, db) {
+    try {
+        const host = req.headers.host;
+        if (!host ||
+            !/^(localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/.test(host) ||
+            (req.headers.origin !== undefined &&
+                req.headers.origin !== `http://${host}`) ||
+            (req.headers["sec-fetch-site"] !== undefined &&
+                !["same-origin", "none"].includes(String(req.headers["sec-fetch-site"])))) {
+            sendJson(res, 403, {
+                error: "Only same-origin local writes are allowed",
+            });
+            return;
+        }
+        if (req.headers["content-type"] !== "application/json") {
+            sendJson(res, 415, { error: "JSON required" });
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of req) {
+            const bytes = Buffer.from(chunk);
+            size += bytes.length;
+            if (size > 32768) {
+                sendJson(res, 413, { error: "Request too large" });
+                return;
+            }
+            chunks.push(bytes);
+        }
+        const input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        const parts = new URL(req.url, `http://${host}`).pathname
+            .split("/")
+            .map(decodeURIComponent);
+        let result;
+        if (parts[2] === "todos")
+            result = parts[3]
+                ? updateTodo(db, parts[3], input)
+                : createTodo(db, input);
+        else {
+            if (!input || typeof input !== "object" || Array.isArray(input))
+                throw new ValidationError("expected an object");
+            const data = input;
+            if (parts[4] === "complete") {
+                if (Object.keys(data).length)
+                    throw new ValidationError("unexpected fields");
+                result = completeActivity(db, parts[3]);
+            }
+            else if (Object.keys(data).length === 1 && "index" in data)
+                result = convertNextStep(db, parts[3], data.index);
+            else {
+                if (Object.keys(data).some((key) => key !== "title"))
+                    throw new ValidationError("unexpected fields");
+                result = createTodo(db, { title: data.title, entryUid: parts[3] });
+            }
+        }
+        sendJson(res, 200, result);
+    }
+    catch (error) {
+        sendJson(res, error instanceof ValidationError ||
+            error instanceof SyntaxError ||
+            error instanceof URIError
+            ? 400
+            : 500, { error: error instanceof Error ? error.message : "Request failed" });
+    }
+}

package/dist/web/locales/en.js

@@ -1,4 +1,20 @@
 export const en = {
+    savedRefreshError: "Saved, but the list could not refresh. Refresh before retrying.",
+    todos: "Todos",
+    todoTitle: "Todo title",
+    addTodo: "Add Todo",
+    complete: "Mark completed",
+    convertTodo: "Convert to Todo",
+    noTodos: "No Todos",
+    noProject: "No project",
+    sourceEntry: "Source activity",
+    reopen: "Reopen",
+    cancelTodo: "Cancel Todo",
+    todo_open: "Open",
+    todo_completed: "Completed",
+    todo_cancelled: "Cancelled",
+    viewTodos: "View Todos",
+    chooseProject: "Assign project",
     htmlLang: "en",
     pageTitle: "Project Manager - Projects & Activity Feed",
     appTitle: "Project Manager",

package/dist/web/locales/zh.d.ts

@@ -1,4 +1,20 @@
 export declare const zh: {
+    readonly savedRefreshError: "已保存，但列表刷新失败。请先刷新页面，不要重复创建。";
+    readonly todos: "待办";
+    readonly todoTitle: "待办内容";
+    readonly addTodo: "新增待办";
+    readonly complete: "标为已完成";
+    readonly convertTodo: "转为待办";
+    readonly noTodos: "暂无待办";
+    readonly noProject: "不关联项目";
+    readonly sourceEntry: "来源动态";
+    readonly reopen: "重新打开";
+    readonly cancelTodo: "取消待办";
+    readonly todo_open: "待办";
+    readonly todo_completed: "已完成";
+    readonly todo_cancelled: "已取消";
+    readonly viewTodos: "查看待办";
+    readonly chooseProject: "关联项目";
     readonly htmlLang: "zh-CN";
     readonly pageTitle: "项目管理 - 项目与动态概览";
     readonly appTitle: "项目管理";

package/dist/web/locales/zh.js

@@ -1,4 +1,20 @@
 export const zh = {
+    savedRefreshError: "已保存，但列表刷新失败。请先刷新页面，不要重复创建。",
+    todos: "待办",
+    todoTitle: "待办内容",
+    addTodo: "新增待办",
+    complete: "标为已完成",
+    convertTodo: "转为待办",
+    noTodos: "暂无待办",
+    noProject: "不关联项目",
+    sourceEntry: "来源动态",
+    reopen: "重新打开",
+    cancelTodo: "取消待办",
+    todo_open: "待办",
+    todo_completed: "已完成",
+    todo_cancelled: "已取消",
+    viewTodos: "查看待办",
+    chooseProject: "关联项目",
     htmlLang: "zh-CN",
     pageTitle: "项目管理 - 项目与动态概览",
     appTitle: "项目管理",

package/dist/web/script.js

@@ -2,11 +2,13 @@ import { getClientI18nScript } from "./i18n.js";
 export function getWebUIScript(initialLang) {
     return `${getClientI18nScript(initialLang)}
 
+    let todosData = [];
     let projectsData = [];
     let historyData = [];
     let focusedEntry = null;
     let activeProjectFilter = null;
     let activeGroupMode = 'grouped';
+    let initialNavigation = true;
 
     function getTodayDateString() {
       const now = new Date();
@@ -32,13 +34,15 @@ export function getWebUIScript(initialLang) {
 
     async function fetchData() {
       try {
-        const [projRes, histRes, statsRes] = await Promise.all([
+        const [projRes, histRes, statsRes, todosRes] = await Promise.all([
           fetch('/api/projects'),
           fetch('/api/history?limit=1000'),
-          fetch('/api/stats')
+          fetch('/api/stats'),
+          fetch('/api/todos')
         ]);
 
-        if (projRes.ok) projectsData = await projRes.json();
+        if (![projRes, histRes, statsRes, todosRes].every(response => response.ok)) throw new Error(t('entryLoadError'));
+        projectsData = await projRes.json();
         if (histRes.ok) historyData = await histRes.json();
         if (statsRes.ok) {
           const stats = await statsRes.json();
@@ -47,24 +51,32 @@ export function getWebUIScript(initialLang) {
           document.getElementById('statUpdates').textContent = stats.totalEntries;
         }
 
+        if (!todosRes.ok) throw new Error('Todos unavailable');
+        todosData = await todosRes.json();
         render();
         if (typeof location !== 'undefined') {
           const ref = new URLSearchParams(location.search).get('entry');
           if (ref) {
-            switchTab('activity');
+            if (initialNavigation) switchTab('activity');
             const response = await fetch('/api/entries/' + encodeURIComponent(ref));
             if (!response.ok) throw new Error('Entry unavailable');
             focusedEntry = await response.json();
             render();
           }
         }
+        initialNavigation = false;
+        return true;
       } catch (err) {
+        document.getElementById('actionError').textContent = t('entryLoadError');
         console.error('Failed to load data', err);
         document.getElementById('timelineContainer').textContent = t('entryLoadError');
+        return false;
       }
     }
 
     function switchTab(tab) {
+      document.getElementById('tabTodos').classList.toggle('active', tab === 'todos');
+      document.getElementById('viewTodos').classList.toggle('active', tab === 'todos');
       document.getElementById('tabProjects').classList.toggle('active', tab === 'projects');
       document.getElementById('tabActivity').classList.toggle('active', tab === 'activity');
       document.getElementById('viewProjects').classList.toggle('active', tab === 'projects');
@@ -176,7 +188,7 @@ export function getWebUIScript(initialLang) {
             <div class="section-box">
               <div class="section-title next-steps">\${escapeHtml(t('nextStepsTitle'))}</div>
               <ul class="bullet-list">
-                \${item.nextSteps.map(n => \`<li>\${escapeHtml(n)}</li>\`).join('')}
+                \${item.nextSteps.map((n, index) => todosData.some(todo => todo.entryUid === (item.nextStepsSourceUid || item.uid) && todo.stepIndex === index) ? '' : \`<li>\${escapeHtml(n)} <button class="btn btn-sm" data-action="convert-todo" data-entry="\${escapeHtml(item.uid)}" data-index="\${index}">\${escapeHtml(t('convertTodo'))}</button></li>\`).join('')}
               </ul>
             </div>
           \` : ''}
@@ -196,6 +208,11 @@ export function getWebUIScript(initialLang) {
             </div>
           \` : ''}
           \${item.completedBy ? '</details>' : ''}
+          <div class="section-box">
+            <button class="btn" data-action="add-todo" data-entry="\${escapeHtml(item.uid)}">\${escapeHtml(t('addTodo'))}</button>
+            \${status !== 'completed' ? \`<button class="btn" data-action="complete-entry" data-entry="\${escapeHtml(item.uid)}">\${escapeHtml(t('complete'))}</button>\` : ''}
+            \${todosData.filter(todo => todo.entryUid === item.uid || todo.entryUid === item.nextStepsSourceUid).map(renderTodo).join('')}
+          </div>
         </div>
       \`;
     }
@@ -214,6 +231,7 @@ export function getWebUIScript(initialLang) {
       const query = document.getElementById('searchInput').value.trim().toLowerCase();
       const selectedDate = document.getElementById('activityDateInput').value;
 
+      renderTodos(query);
       // Render Active Filter Chip
       const filterBar = document.getElementById('filterBarContainer');
       const chip = document.getElementById('activeFilterChip');
@@ -271,6 +289,7 @@ export function getWebUIScript(initialLang) {
               </div>
               <div class="card-footer">
                 <span>\${escapeHtml(t('createdLabel'))} \${formatTime(p.createdAt)}</span>
+                <button class="btn" data-action="project-todos" data-project="\${escapeHtml(p.project)}">\${escapeHtml(t('viewTodos'))}</button>
                 <a class="link-btn" data-action="filter-project" data-project="\${escapeHtml(p.project)}">\${escapeHtml(t('viewActivity'))}</a>
               </div>
             </div>
@@ -352,5 +371,70 @@ export function getWebUIScript(initialLang) {
         .replace(/'/g, '&#039;');
     }
 
+
+    function projectOptions(selected) {
+      return '<option value="">' + escapeHtml(t('noProject')) + '</option>' + projectsData.map(p =>
+        '<option value="' + escapeHtml(p.project) + '"' + (selected === p.project ? ' selected' : '') + '>' + escapeHtml(p.displayName) + '</option>').join('');
+    }
+    function renderTodo(todo) {
+      return '<div class="section-box"><strong>' + escapeHtml(todo.title) + '</strong> · ' + escapeHtml(t('todo_' + todo.status)) +
+        (todo.project ? ' · ' + escapeHtml(todo.project) : '') +
+        (todo.entryUid ? ' <a class="link-btn" href="?entry=' + encodeURIComponent(todo.entryUid) + '">' + escapeHtml(t('sourceEntry')) + '</a>' :
+          ' <label>' + escapeHtml(t('chooseProject')) + ' <select data-todo-project="' + escapeHtml(todo.uid) + '">' + projectOptions(todo.project) + '</select></label>') +
+        ' <button class="btn" data-action="todo-status" data-uid="' + escapeHtml(todo.uid) + '" data-status="' + (todo.status === 'open' ? 'completed' : 'open') + '">' + escapeHtml(t(todo.status === 'open' ? 'complete' : 'reopen')) + '</button>' +
+        (todo.status === 'open' ? ' <button class="btn" data-action="todo-status" data-uid="' + escapeHtml(todo.uid) + '" data-status="cancelled">' + escapeHtml(t('cancelTodo')) + '</button>' : '') + '</div>';
+    }
+    function renderTodos(query) {
+      const select = document.getElementById('todoProject');
+      select.innerHTML = projectOptions(select.value);
+      const todos = todosData.filter(todo => (!activeProjectFilter || todo.project === activeProjectFilter) &&
+        (!query || (todo.title + ' ' + (todo.project || '')).toLowerCase().includes(query)));
+      document.getElementById('todosContainer').innerHTML = todos.length ? todos.map(renderTodo).join('') : '<p>' + escapeHtml(t('noTodos')) + '</p>';
+    }
+    async function mutate(path, data) {
+      const response = await fetch(path, {method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(data)});
+      const result = await response.json();
+      if (!response.ok) throw new Error(result.error || 'Request failed');
+      if (!await fetchData()) { const error = new Error(t('savedRefreshError')); error.saved = true; throw error; }
+    }
+    async function runAction(element, action) {
+      if (element.disabled) return;
+      element.disabled = true;
+      document.getElementById('actionError').textContent = '';
+      try { await action(); }
+      catch (error) { document.getElementById('actionError').textContent = error.message; }
+      finally { element.disabled = false; }
+    }
+    document.getElementById('todoForm').addEventListener('submit', function(event) {
+      event.preventDefault();
+      const button = this.querySelector('button');
+      runAction(button, async () => {
+        try {
+          await mutate('/api/todos', {title: document.getElementById('todoTitle').value, project: document.getElementById('todoProject').value || null});
+          document.getElementById('todoTitle').value = '';
+        } catch (error) {
+          if (error.saved) document.getElementById('todoTitle').value = '';
+          throw error;
+        }
+      });
+    });
+    document.addEventListener('change', function(event) {
+      const select = event.target.closest('[data-todo-project]');
+      if (select) runAction(select, () => mutate('/api/todos/' + select.dataset.todoProject, {project: select.value || null}));
+    });
+    document.addEventListener('click', function(event) {
+      const button = event.target.closest('[data-action]');
+      if (!button) return;
+      const data = button.dataset;
+      if (data.action === 'project-todos') { activeProjectFilter = data.project; switchTab('todos'); render(); document.getElementById('todoProject').value = data.project; return; }
+      if (data.action === 'complete-entry') runAction(button, () => mutate('/api/entries/' + data.entry + '/complete', {}));
+      if (data.action === 'convert-todo') runAction(button, () => mutate('/api/entries/' + data.entry + '/todos', {index: Number(data.index)}));
+      if (data.action === 'todo-status') runAction(button, () => mutate('/api/todos/' + data.uid, {status: data.status}));
+      if (data.action === 'add-todo') {
+        const title = window.prompt(t('todoTitle'));
+        if (title && title.trim()) runAction(button, () => mutate('/api/entries/' + data.entry + '/todos', {title}));
+      }
+    });
+
     fetchData();`;
 }

package/dist/web/ui.js

@@ -45,6 +45,7 @@ ${WEB_UI_STYLES}
     <div class="nav-tabs">
       <button class="tab-btn active" id="tabProjects" data-i18n="projects" onclick="switchTab('projects')">${dict.projects}</button>
       <button class="tab-btn" id="tabActivity" data-i18n="activityFeed" onclick="switchTab('activity')">${dict.activityFeed}</button>
+      <button class="tab-btn" id="tabTodos" data-i18n="todos" onclick="switchTab('todos')">${dict.todos}</button>
     </div>
     <button class="btn" id="btnRefresh" data-i18n="refresh" onclick="refreshData()">${dict.refresh}</button>
   </div>
@@ -54,6 +55,17 @@ ${WEB_UI_STYLES}
       <span id="labelFilterByProject" data-i18n="filteringByProject">${dict.filteringByProject}</span> <span id="activeFilterChip" class="filter-chip"></span>
     </div>
 
+    <div id="actionError" role="alert"></div>
+    <div id="viewTodos" class="view-panel">
+      <form id="todoForm" class="section-box">
+        <label for="todoTitle" data-i18n="todoTitle">${dict.todoTitle}</label>
+        <input id="todoTitle" class="search-input" required maxlength="2000" />
+        <label for="todoProject" data-i18n="projects">${dict.projects}</label>
+        <select id="todoProject" class="date-input"></select>
+        <button class="btn" type="submit" data-i18n="addTodo">${dict.addTodo}</button>
+      </form>
+      <div id="todosContainer"></div>
+    </div>
     <!-- Projects View -->
     <div id="viewProjects" class="view-panel active">
       <div id="projectsContainer" class="projects-grid"></div>

package/package.json

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

package/skills/project-mgr/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: project-mgr
-description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, set project descriptions/notes, list or fuzzy-search projects, start the local Web Dashboard, import status records, query current or historical project state, or export a status ledger.
+description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, set project descriptions/notes, list or fuzzy-search projects, start the local Web Dashboard, import status records, query current or historical project state, or export a status ledger. When one effort contains multiple sub-projects, ask whether they share one project name or should be distinguished with tags.
 ---
 
 # project-mgr
 
 ## CLI selection
 
-Prefer an installed `pmgr`: locate it with `command -v pmgr` and check the installed package metadata/documentation for the required version and capabilities. The current CLI does not implement `--help` or `--version`; do not use those flags as health checks. In a source checkout, use `pnpm pmgr` only when the local dependencies are already installed and the package manager is available without downloading it.
+Prefer an installed `pmgr`: locate it with `command -v pmgr` and check the installed package metadata/documentation for the required version and capabilities. This source revision supports `-h` / `--help`, `help [command]`, and `-v` / `-V` / `--version` / `version` without opening the database. Older installed releases may not support these flags; inspect their package metadata instead. In a source checkout, use `pnpm pmgr` only when the local dependencies are already installed and the package manager is available without downloading it.
 
 Do not automatically install or upgrade dependencies, or fall back to `npx` / `npm exec`. If no usable CLI is available, report the missing executable, dependency, or capability and the setup needed. Perform installation or upgrades only when the user authorizes that setup.
 
@@ -23,6 +23,7 @@ Completion links and version-2 exports require project-mgr 0.3.0 or later. This
 - Set `--source agent` for agent-authored updates. Use `--external-ref` only when a stable idempotency key is available.
 - Explicitly pass `--status` on every `add`, and include `status` in every agent-authored import entry. The CLI defaults to `completed`; do not rely on that default. Choose the status from the evidence and inspect the current snapshot when unclear. Completing one activity does not necessarily complete the project; use `active` when project work continues. If the status remains uncertain, clarify before writing.
 - If the project is not yet in the ledger database, initialize its metadata with `set-project`. Backfill only milestones supported by verifiable Git commits, dated documents, or historical records, and include the evidence reference in `--progress`. Use historical `--at` timestamps only when supported by that evidence; a commit timestamp proves a commit, not a deployment. There is no required number of entries. Never invent milestones or dates; when evidence is unavailable, skip backfill and append only the current known status.
+- If one effort contains multiple sub-projects and the user has not already chosen how to identify them, ask before writing. See "Multiple sub-projects".
 
 ## Metadata vs. status entries
 
@@ -31,7 +32,20 @@ Completion links and version-2 exports require project-mgr 0.3.0 or later. This
   - **Do NOT** put transient progress, session logs, or one-off status messages into `--notes`.
   - Avoid passing `--notes` during routine `add` commands to prevent accidentally overwriting long-term project notes.
 - **Project description (`--description`)**: A high-level, stable summary of the project's purpose.
-- **Status snapshots (`add`)**: Use `--summary` (concise milestone headline), `--progress` (detailed work accomplished), `--next` (immediate next steps), `--blocker` (current obstacles), and `--decision` for transactional, append-only updates.
+- **Status snapshots (`add`)**: Use `--summary` (concise milestone headline), `--progress` (detailed work accomplished), `--next` (immediate next steps), `--blocker` (current obstacles), `--decision`, and repeatable `--tag` for transactional, append-only updates.
+
+## Multiple sub-projects
+
+One repository or effort may contain several sub-projects, such as separate packages, apps, services, or contracts. `--project` is the ledger identity: current status, history, and completion links all belong to that slug. `--tag` is a repeatable label on a single status snapshot. Tags do not create a project, a separate current status, or a separate completion history. `projects` / `list --query` can match tags on the latest snapshot.
+
+When several sub-projects are in scope and the user has not already chosen how to identify them, ask before the first write. Do not decide silently. Do not create a separate project slug per sub-project unless the user explicitly asks for separate ledger projects.
+
+Offer these two choices:
+
+1. **Share one project name.** Append every sub-project to the same `--project`. Use this when the user wants one current status and one history for the whole effort. Do not add sub-project tags unless the user also asks for them.
+2. **Distinguish sub-projects with tags.** Keep that same `--project`, and pass repeatable `--tag` values naming the sub-project this snapshot covers, for example `--project acme --tag web`. Reuse the same tag on later updates for that sub-project. A tag describes that snapshot only; older snapshots keep the tags they were written with. Search with `pmgr list --query web --json`. Completion links still apply to the whole project, so link an earlier entry only when this update resolves all of that entry's commitments.
+
+Follow a choice the user already recorded. Do not store the choice in `--notes` unless the user asks; notes are long-term project context, and `set-project --notes` replaces them.
 
 ## Operations
 
@@ -53,6 +67,10 @@ pmgr serve --port 3000 --no-open --json
 pmgr add --project my-project --status active --summary "Implemented the CLI" \
   --progress "Tests pass" --next "Publish the package" --source agent --json
 
+# Same project, with a tag naming the sub-project this snapshot covers.
+pmgr add --project acme --status active --summary "Shipped the web dashboard" \
+  --tag web --source agent --json
+
 # Query current state, history, or state at a time.
 pmgr current --project my-project --json
 pmgr history --project my-project --limit 20 --json