projectkeeper 0.0.0-stage → 1.0.0

package/template/examples/papertrail.json

@@ -0,0 +1,747 @@
+{
+  "$schema": "../projectkeeper.schema.json",
+  "format": "projectkeeper.table/1",
+  "project": {
+    "name": "Papertrail",
+    "asOf": {
+      "date": "2026-09-20",
+      "repos": [
+        {
+          "path": ".",
+          "commit": "a1b2c3d"
+        }
+      ]
+    },
+    "filledBy": {
+      "agent": "Example, written by hand for the template (commit numbers are placeholders)",
+      "at": "2026-10-13",
+      "read": "README, AGENTS.md, docs/PRODUCT.md, PLAN.md, TASKS.md and DECISIONS.md in full; the receipts and the reader design; the five source files; the git log. Then the three owner conversations in the session material."
+    }
+  },
+  "ownerWants": [
+    {
+      "id": "W1",
+      "want": "Saving a page must be quicker than deciding where it goes.",
+      "kind": "Product",
+      "status": "Current",
+      "said": [
+        {
+          "session": "claude:sess_fixture_own1",
+          "message": 2,
+          "quote": "Saving has to be faster than deciding where it goes."
+        }
+      ],
+      "reflectedIn": [
+        "G1",
+        "A1",
+        "REQ-C1"
+      ]
+    },
+    {
+      "id": "W2",
+      "want": "No accounts, ever.",
+      "kind": "Product",
+      "status": "Current",
+      "said": [
+        {
+          "session": "claude:sess_fixture_own1",
+          "message": 4,
+          "quote": "If it needs an account, it is dead to me."
+        }
+      ],
+      "reflectedIn": [
+        "DEC-1"
+      ]
+    },
+    {
+      "id": "W3",
+      "want": "Search answers within a second, and comes before other polish.",
+      "kind": "Product",
+      "status": "Current",
+      "said": [
+        {
+          "session": "claude:sess_fixture_own2",
+          "message": 3,
+          "quote": "搜索要在一秒内出结果，不然我不会用。"
+        },
+        {
+          "session": "claude:sess_fixture_own2",
+          "message": 9,
+          "quote": "可以，先做搜索。"
+        }
+      ],
+      "reflectedIn": [
+        "A3",
+        "REQ-S1",
+        "T-18"
+      ]
+    },
+    {
+      "id": "W4",
+      "want": "Tags grow by themselves; the owner never maintains a tag system.",
+      "kind": "Product",
+      "status": "Current",
+      "said": [
+        {
+          "session": "claude:sess_fixture_own2",
+          "message": 5,
+          "quote": "我不想维护标签体系，它自己长出来。"
+        }
+      ],
+      "reflectedIn": [
+        "A5",
+        "REQ-T1"
+      ]
+    },
+    {
+      "id": "W5",
+      "want": "Sharing waits; nobody has asked for it.",
+      "kind": "Product",
+      "status": "Current",
+      "said": [
+        {
+          "session": "claude:sess_fixture_own3",
+          "message": 6,
+          "quote": "Sharing is a nice-to-have; nobody asked for it."
+        }
+      ],
+      "reflectedIn": [
+        "A6"
+      ]
+    },
+    {
+      "id": "W6",
+      "want": "Task numbers follow docs/TASKS.md.",
+      "kind": "Way of working",
+      "status": "Current",
+      "said": [
+        {
+          "session": "claude:sess_fixture_own3",
+          "message": 10,
+          "quote": "对，编号以 TASKS.md 为准。"
+        }
+      ],
+      "reflectedIn": []
+    }
+  ],
+  "product": {
+    "id": "Papertrail",
+    "name": "Papertrail",
+    "forWhom": "One person keeping their own read-later list.",
+    "summary": "A one-person read-later list. Save a page in one motion, read it offline, find it again with one query. The list belongs to the owner: plain files, export anytime.",
+    "sources": [
+      {
+        "file": "README.md",
+        "lines": "1-7"
+      }
+    ]
+  },
+  "goals": [
+    {
+      "id": "G1",
+      "name": "Save in one motion, find in one query",
+      "summary": "Saving and finding cost one action each.",
+      "status": "Current",
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "5",
+          "quote": "G1 · Save in one motion, find in one query."
+        }
+      ]
+    },
+    {
+      "id": "G2",
+      "name": "Read anywhere, offline first",
+      "summary": "Every saved page reads without a connection.",
+      "status": "Current",
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "5",
+          "quote": "G2 · Read anywhere, offline first."
+        }
+      ]
+    },
+    {
+      "id": "G3",
+      "name": "数据永远属于自己",
+      "summary": "Plain files, exportable, no account.",
+      "status": "Current",
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "5",
+          "quote": "G3 · 数据永远属于自己."
+        }
+      ]
+    }
+  ],
+  "areas": [
+    {
+      "id": "A1",
+      "name": "Capture 快速收藏",
+      "summary": "One shortcut, no dialog.",
+      "status": "Current",
+      "goals": [
+        "G1"
+      ],
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "9"
+        }
+      ]
+    },
+    {
+      "id": "A2",
+      "name": "Reading 阅读体验",
+      "summary": "Offline, calm typography.",
+      "status": "Current",
+      "goals": [
+        "G2"
+      ],
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "10"
+        }
+      ]
+    },
+    {
+      "id": "A3",
+      "name": "Search 搜索与找回",
+      "summary": "Full text, under a second.",
+      "status": "Current",
+      "goals": [
+        "G1"
+      ],
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "11"
+        }
+      ]
+    },
+    {
+      "id": "A4",
+      "name": "Sync 同步",
+      "summary": "Deferred until after v1.",
+      "status": "Deferred",
+      "why": "Deferred until after v1.",
+      "goals": [
+        "G2"
+      ],
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "12"
+        }
+      ]
+    },
+    {
+      "id": "A5",
+      "name": "Tags 标签与整理",
+      "summary": "Tags suggest themselves.",
+      "status": "Current",
+      "goals": [
+        "G1"
+      ],
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "13"
+        }
+      ]
+    },
+    {
+      "id": "A6",
+      "name": "Sharing 分享",
+      "summary": "Proposed, not scheduled.",
+      "status": "Proposed",
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "14"
+        }
+      ]
+    },
+    {
+      "id": "A7",
+      "name": "Import & export 导入导出",
+      "summary": "Plain text only.",
+      "status": "Current",
+      "goals": [
+        "G3"
+      ],
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "15"
+        }
+      ]
+    }
+  ],
+  "requirements": [
+    {
+      "id": "REQ-C1",
+      "name": "One shortcut saves the current page",
+      "summary": "A global shortcut saves the current page without a dialog.",
+      "status": "Current",
+      "place": {
+        "area": "A1"
+      },
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "9"
+        }
+      ]
+    },
+    {
+      "id": "REQ-S1",
+      "name": "Search returns in under one second for 5,000 items",
+      "summary": "Search answers within a second over 5,000 saved pages.",
+      "status": "Current",
+      "place": {
+        "area": "A3"
+      },
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "11"
+        }
+      ]
+    },
+    {
+      "id": "REQ-T1",
+      "name": "Tags suggest themselves",
+      "summary": "Tags are suggested from the text; nobody maintains a tag system.",
+      "status": "Current",
+      "place": {
+        "area": "A5"
+      },
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "13"
+        }
+      ]
+    }
+  ],
+  "designs": [
+    {
+      "id": "Reader layout v2",
+      "name": "Reader layout v2 阅读版式",
+      "summary": "Single column, 68 characters per line, system fonts only.",
+      "status": "Current",
+      "place": {
+        "area": "A2"
+      },
+      "sources": [
+        {
+          "file": "docs/design/reader-layout.md",
+          "lines": "1-3"
+        }
+      ]
+    }
+  ],
+  "decisions": [
+    {
+      "id": "DEC-1",
+      "name": "No accounts 不做账号",
+      "summary": "No accounts; the list is local files.",
+      "status": "Current",
+      "place": {
+        "wholeProduct": "It decides how every part stores the list."
+      },
+      "sources": [
+        {
+          "file": "docs/DECISIONS.md",
+          "lines": "3"
+        }
+      ]
+    },
+    {
+      "id": "DEC-2",
+      "name": "搜索取代标签浏览器",
+      "summary": "Full-text search replaces the tag browser.",
+      "status": "Current",
+      "place": {
+        "area": "A3"
+      },
+      "sources": [
+        {
+          "file": "docs/DECISIONS.md",
+          "lines": "4"
+        }
+      ]
+    },
+    {
+      "id": "DEC-3",
+      "name": "Export is a folder of Markdown files",
+      "summary": "Export writes a folder of Markdown files.",
+      "status": "Current",
+      "place": {
+        "area": "A7"
+      },
+      "sources": [
+        {
+          "file": "docs/DECISIONS.md",
+          "lines": "5"
+        }
+      ]
+    },
+    {
+      "id": "DEC-5",
+      "name": "Word counts are part of the search index",
+      "summary": "Word counts were indexed.",
+      "status": "Replaced",
+      "replacedBy": "DEC-6",
+      "why": "DEC-6 took it back.",
+      "place": {
+        "area": "A3"
+      },
+      "sources": [
+        {
+          "file": "docs/DECISIONS.md",
+          "lines": "6"
+        }
+      ]
+    },
+    {
+      "id": "DEC-6",
+      "name": "Word counts stay out of the search index",
+      "summary": "Word counts stay out of the search index.",
+      "status": "Current",
+      "place": {
+        "area": "A3"
+      },
+      "sources": [
+        {
+          "file": "docs/DECISIONS.md",
+          "lines": "7"
+        }
+      ]
+    },
+    {
+      "id": "B-1",
+      "name": "v1 不做任何社交功能",
+      "summary": "v1 has no social features.",
+      "status": "Current",
+      "boundary": true,
+      "place": {
+        "area": "A6"
+      },
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "19"
+        }
+      ]
+    },
+    {
+      "id": "B-2",
+      "name": "No server of our own in v1",
+      "summary": "v1 runs without a server of its own.",
+      "status": "Current",
+      "boundary": true,
+      "place": {
+        "area": "A4"
+      },
+      "sources": [
+        {
+          "file": "docs/PRODUCT.md",
+          "lines": "19"
+        }
+      ]
+    }
+  ],
+  "plans": [
+    {
+      "id": "PLAN-1",
+      "name": "v1 milestone: save, read, find",
+      "summary": "Capture, reader and first search.",
+      "status": "Current",
+      "sources": [
+        {
+          "file": "docs/PLAN.md",
+          "lines": "3-5"
+        }
+      ]
+    },
+    {
+      "id": "PLAN-2",
+      "name": "秋季打磨：搜索、导出与中文体验",
+      "summary": "Chinese tokenization, export attachments, search filters.",
+      "status": "Current",
+      "sources": [
+        {
+          "file": "docs/PLAN.md",
+          "lines": "7-9"
+        }
+      ]
+    },
+    {
+      "id": "PLAN-3",
+      "name": "Sync evaluation 同步评估",
+      "summary": "Evaluate sync after the owner reviews v1.",
+      "status": "Deferred",
+      "why": "Deferred until the owner reviews v1.",
+      "sources": [
+        {
+          "file": "docs/PLAN.md",
+          "lines": "11-13"
+        }
+      ]
+    }
+  ],
+  "work": [
+    {
+      "id": "T-1",
+      "name": "Global hotkey capture",
+      "summary": "One shortcut saves the page.",
+      "plan": "PLAN-1",
+      "area": "A1",
+      "implements": [
+        "REQ-C1"
+      ],
+      "status": "Current",
+      "progress": "Done",
+      "sources": [
+        {
+          "file": "docs/TASKS.md",
+          "lines": "5"
+        }
+      ]
+    },
+    {
+      "id": "T-2",
+      "name": "Save with note field",
+      "summary": "A note saves together with the page.",
+      "plan": "PLAN-1",
+      "area": "A1",
+      "status": "Current",
+      "progress": "Done",
+      "sources": [
+        {
+          "file": "docs/TASKS.md",
+          "lines": "6"
+        }
+      ]
+    },
+    {
+      "id": "T-15",
+      "name": "SQLite FTS index",
+      "summary": "Full-text search over title and body.",
+      "plan": "PLAN-1",
+      "area": "A3",
+      "status": "Current",
+      "progress": "Done",
+      "sources": [
+        {
+          "file": "docs/TASKS.md",
+          "lines": "9"
+        }
+      ]
+    },
+    {
+      "id": "T-24",
+      "name": "Tag browser v1",
+      "summary": "Browse saved pages by tag.",
+      "plan": "PLAN-1",
+      "area": "A3",
+      "alsoAreas": [
+        "A5"
+      ],
+      "status": "Replaced",
+      "replacedBy": "T-18",
+      "progress": "On hold",
+      "sources": [
+        {
+          "file": "docs/TASKS.md",
+          "lines": "12",
+          "quote": "replaced by T-18"
+        }
+      ]
+    },
+    {
+      "id": "T-18",
+      "name": "Search index incremental rebuild",
+      "summary": "The index refreshes without a full rebuild.",
+      "plan": "PLAN-2",
+      "area": "A3",
+      "implements": [
+        "REQ-S1"
+      ],
+      "status": "Current",
+      "progress": "In progress",
+      "open": "The receipt says it refreshes every minute; the code has no background refresh.",
+      "sources": [
+        {
+          "file": "docs/TASKS.md",
+          "lines": "10"
+        }
+      ]
+    },
+    {
+      "id": "T-19",
+      "name": "中文分词接入",
+      "summary": "Chinese text matches by word, not by character.",
+      "plan": "PLAN-2",
+      "area": "A3",
+      "status": "Current",
+      "progress": "In progress",
+      "sources": [
+        {
+          "file": "docs/TASKS.md",
+          "lines": "11"
+        }
+      ]
+    },
+    {
+      "id": "T-25",
+      "name": "Sync protocol spike",
+      "summary": "Try a sync protocol between two machines.",
+      "plan": "PLAN-3",
+      "area": "A4",
+      "status": "Deferred",
+      "why": "Waits for PLAN-3.",
+      "progress": "Planned",
+      "sources": [
+        {
+          "file": "docs/TASKS.md",
+          "lines": "13"
+        }
+      ]
+    },
+    {
+      "id": "T-31",
+      "name": "Markdown export",
+      "summary": "Export a folder of Markdown files.",
+      "plan": "PLAN-2",
+      "area": "A7",
+      "implements": [
+        "DEC-3"
+      ],
+      "status": "Current",
+      "progress": "Done",
+      "sources": [
+        {
+          "file": "docs/TASKS.md",
+          "lines": "14"
+        }
+      ]
+    }
+  ],
+  "code": [
+    {
+      "id": "capture",
+      "name": "Capture",
+      "summary": "The global shortcut and the save path.",
+      "area": "A1",
+      "paths": [
+        "src/capture.ts"
+      ]
+    },
+    {
+      "id": "reader",
+      "name": "Reader",
+      "summary": "Offline reading with system fonts.",
+      "area": "A2",
+      "paths": [
+        "src/reader.ts"
+      ]
+    },
+    {
+      "id": "search",
+      "name": "Search",
+      "summary": "SQLite FTS5; rebuilds when the app opens.",
+      "area": "A3",
+      "paths": [
+        "src/search.ts"
+      ]
+    },
+    {
+      "id": "sync",
+      "name": "Sync",
+      "summary": "A placeholder; nothing runs.",
+      "area": "A4",
+      "paths": [
+        "src/sync.ts"
+      ],
+      "anomalies": [
+        {
+          "kind": "Looks residual, is live",
+          "text": "Sync is deferred, yet the file still ships with the app.",
+          "sources": [
+            {
+              "file": "src/sync.ts",
+              "lines": "1"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "export",
+      "name": "Export",
+      "summary": "A folder of Markdown files; attachments still to do.",
+      "area": "A7",
+      "paths": [
+        "src/export.ts"
+      ]
+    }
+  ],
+  "notes": [
+    {
+      "id": "N-1",
+      "title": "Batch 2 says the index refreshes every minute; the code does not.",
+      "kind": "Anomaly",
+      "ask": "For your decision",
+      "on": [
+        "T-18"
+      ],
+      "text": "The receipt for batch 2 claims a background refresh every minute and was signed off. src/search.ts says the index rebuilds only when the app opens. Search speed is what the owner cares about most (W3).",
+      "options": [
+        {
+          "choice": "Reopen T-18 to build the background refresh",
+          "consequence": "Search stays fresh while the app is open; one more task in PLAN-2."
+        },
+        {
+          "choice": "Correct the receipt",
+          "consequence": "The record matches the code; the index stays stale until the app restarts."
+        }
+      ],
+      "sources": [
+        {
+          "file": "docs/receipts/batch-2.md",
+          "lines": "5",
+          "quote": "The search index now refreshes itself every minute in the background."
+        },
+        {
+          "file": "src/search.ts",
+          "lines": "1"
+        }
+      ],
+      "by": "Project"
+    },
+    {
+      "id": "N-2",
+      "title": "Numbering by TASKS.md is the owner's rule, but no document says so.",
+      "kind": "Owner and project differ",
+      "ask": "For information",
+      "on": [
+        "W6"
+      ],
+      "text": "The owner confirmed that task numbers follow docs/TASKS.md. AGENTS.md says every task gets the next number there, but not that TASKS.md wins when numbers disagree.",
+      "sources": [
+        {
+          "file": "AGENTS.md",
+          "lines": "3"
+        }
+      ],
+      "by": "Main agent"
+    }
+  ]
+}