{title}

[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_731":732,"_733":734},"routes/_app.x.$handle.$name",{"_98":97,"_31":43,"_106":88,"_26":107,"_13":14,"_108":-5,"_11":109,"_110":111,"_112":113,"_114":115,"_116":117,"_20":-5,"_118":-5,"_119":-5,"_120":24,"_121":122,"_123":57,"_124":-5,"_125":-5,"_126":127},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_41":42,"_31":43,"_36":44,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":55,"_56":57,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":81,"_82":83,"_84":85,"_86":24},"version",316,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":-7,"_23":24,"_25":24,"_26":27,"_28":27},"file",{"_29":30,"_31":32,"_33":20,"_34":35,"_36":37,"_38":14,"_39":40,"_23":24},"previous","deleted",false,"deletedHere","path","docs/agents/design.md","latestPath","fileId","3e7942aa-7fe8-11f1-865e-1607ee4eb77e","name","design.md","fileType","content","# Design Docs\n\nHow the design skills should consume this repo's design documentation when\nworking on any user-visible surface.\n\n## Before touching UI, read these\n\n- **`PRODUCT.md`** at the repo root — strategy. Register (`product`), who the\n users are, brand personality, anti-references, design principles.\n- **`DESIGN.md`** at the repo root — the visual system. YAML frontmatter carries\n the tokens and is **normative**; the prose explains how to apply them.\n- **`.impeccable/design.json`** — sidecar. Tonal ramps, motion, the focus-ring\n token, and drop-in HTML/CSS for ten components. Read it when you need an exact\n component treatment; `DESIGN.md` is the readable layer over it.\n\nIf any of these don't exist, **proceed silently**. Don't flag their absence.\nThey are created by `/impeccable init` and `/impeccable document`.\n\n## Status: DESIGN.md is a target, not a description\n\n**This is the thing to know before you trust either file.**\n\n`DESIGN.md` documents the system the tracker is **moving to**, derived from Val\nTown's live design system. The code has **not** been migrated to it yet. As of\n2026-07-14, `theme.ts` still holds the pre-migration palette, and the two\ndirectly contradict each other:\n\n| Concern | `theme.ts` today | `DESIGN.md` target |\n| ------- | ----------------------- | -------------------------------------- |\n| Canvas | `#0f1115` blue-charcoal | `#ffffff` / `#000000` |\n| Accent | `#3d7bf0` blue | `#0069a8` / `#00bcff` (Val Town `sky`) |\n| Borders | `#2a2f3a` | `#e2e8f0` / `#314158` (slate) |\n| Type | bare `font-sans` stack | IBM Plex Sans + iA Writer Mono |\n| Scheme | dark only | dual, via `prefers-color-scheme` |\n\nSo: **when the code and `DESIGN.md` disagree, `DESIGN.md` wins as the target,\nbut do not assume the surrounding code already follows it.** Don't \"fix\"\n`DESIGN.md` to match `theme.ts`. Don't cite existing code as precedent for a\ntoken choice — most of it predates the spec. The migration is tracked in\n`docs/backlog.md`. Delete this section once `theme.ts` matches the spec.\n\n## The UI surface\n\nAll user-visible rendering is server-rendered Hono TSX, styled with Twind\nutility classes. Four files, in dependency order:\n\n```\ntheme.ts → the palette. No local imports, so it can never create a cycle.\nui.tsx → primitives (Button, Card, Select, Banner, StatusBadge, LabelTag)\nlayout.tsx → the shell and the 64px top bar\ncomponents.tsx → the pages (list rows, detail, labels, create/edit)\n```\n\n`theme.ts` is the **single source of truth for the palette**. A recurring color\nbelongs there; genuine one-offs stay inline. Don't introduce a second palette\nmodule, and don't hardcode a hex in `components.tsx` that `theme.ts` already\nnames.\n\n## Constraints that outrank visual preference\n\n- **Zero-JS.** Every interaction is a link, a form post, or a native `

`\n disclosure. This is a PRD-level contract, not a style. A design that needs\n client JS to work is wrong here regardless of how it looks. Any JS must be an\n enhancement the page works without.\n- **It embeds politely.** The tracker is a guest in a host val. One slim bar of\n chrome; it never assumes it owns the page. This is why the target is\n dual-scheme rather than dark-only.\n- **Role boundaries render as absences.** What a user can't do isn't shown\n disabled or explained — it's absent.\n- **User label colors are sacred.** A label's stored `color` is user-authored\n and always wins over the palette.\n\n## Don't conflate the four root docs\n\n| File | Answers | Owned by |\n| ------------ | --------------------------- | ------------------ |\n| `CONTEXT.md` | what the words mean | `/domain-modeling` |\n| `docs/adr/` | why it was decided that way | `/domain-modeling` |\n| `PRODUCT.md` | who it's for and why | `/impeccable init` |\n| `DESIGN.md` | how it looks | `/impeccable` |\n\n`DESIGN.md` is **strictly visual**. Domain vocabulary lives in `CONTEXT.md` —\nuse its terms (Issue, Body, Status, State Reason, Blocked, Event) in UI copy and\ncomponent names rather than drifting to synonyms. See `domain.md`.\n\nNote the two label axes, per `triage-labels.md`: the tracker _product's_ labels\n(`bug`, `enhancement`, …) are what `LabelTag` renders. The workflow triage\nlabels (`ready-for-agent`, …) are a different axis and are not a UI concern.\n\n## Flag DESIGN.md conflicts\n\nIf your work contradicts a Named Rule, surface it rather than silently\noverriding — the same way ADR conflicts get surfaced:\n\n> _Contradicts The No-Card Rule (one panel, hairline rows) — but worth reopening\n> because…_\n\nThe Named Rules in `DESIGN.md` (The Encoded Color Rule, The Achromatic Canvas\nRule, The Hairline Rule, The Machine Facts Rule, The One Bold Rule, The Badge\nContainment Rule, The Flat-Forever Rule, The No-Card Rule) are the citable unit.\nQuote them by name.\n","createdAt",["D",1784077088196],"branchVersion","branchId","b6817ee5-03f4-41f2-901e-1bb2efa16e9e","id","abe99189-4851-4aab-ae08-280f66283cac","val-issue-tracker",["D",1783563523910],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Per-val issue tracker — import into any val for scoped issues","imageUrl","5d1042a9-7b0b-499d-8a72-3a8ac7a4e185","pinnedFileId","d1d90306-7b3c-11f1-b527-1607ee4eb77e","pinPreview",true,"pinMigrated","screenshotVersion","likeCount",0,"orgId","5f80108f-7ca4-4327-b77b-089dbe4b5a82","tursoName","abe9918948514aabae08280f66283cac","tursoHostname","abe9918948514aabae08280f66283cac-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789525245864],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_98":97,"_105":101},"org",{"_98":97,"_99":-5,"_100":101,"_18":53,"_102":103,"_104":24},"branch",{"_13":87,"_31":88,"_41":40,"_89":42,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":43,"_96":97},"isOwned",369,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","nbbaier","handle","displayName","avatar","https://secure.gravatar.com/avatar/0129a541b7b3574e92c4afd06c5e32da&d=identicon","tier","pro","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_41":42,"_31":43,"_36":726,"_45":-5,"_46":24,"_47":48,"_49":48,"_50":51,"_52":-5,"_18":53,"_54":55,"_56":57,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":65,"_66":67,"_68":727,"_70":-5,"_71":72,"_73":72,"_74":75,"_76":75,"_77":75,"_78":72,"_79":72,"_80":728,"_82":729,"_84":730,"_86":24},"tree",[343,344,372,379,380,381,382,383,384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399],"files",[343,344,345,346,347,348,349,350,351,352,353,354,355,356,357,358,359,360,361,362,363,364,365,366,367,368,369,370,371,372,373,374,375,376,377,378,379,380,381,382,383,384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399],"counts",{"_333":61,"_334":215,"_335":61,"_336":337,"_338":339},"contents",[128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_41":327,"_31":328,"_29":329,"_155":-5,"_39":40,"_38":330,"_157":57,"_36":331,"_13":61,"_33":319,"_34":-5,"_23":24,"_162":-5,"_26":332},{"_41":321,"_31":322,"_29":323,"_155":-5,"_39":40,"_38":324,"_157":57,"_36":325,"_13":61,"_33":319,"_34":-5,"_23":24,"_162":-5,"_26":326},{"_41":314,"_31":315,"_29":316,"_155":-5,"_39":40,"_38":317,"_157":57,"_36":318,"_13":61,"_33":319,"_34":-5,"_23":24,"_162":-5,"_26":320},{"_41":307,"_31":308,"_29":309,"_155":-5,"_39":40,"_38":310,"_157":57,"_36":311,"_13":61,"_33":20,"_34":312,"_23":24,"_162":-5,"_26":313},{"_41":301,"_31":302,"_29":303,"_155":-5,"_39":40,"_38":304,"_157":24,"_36":305,"_13":215,"_33":20,"_34":299,"_23":24,"_162":-5,"_26":306},{"_41":294,"_31":295,"_29":296,"_155":-5,"_39":40,"_38":297,"_157":24,"_36":298,"_13":215,"_33":20,"_34":299,"_23":24,"_162":-5,"_26":300},{"_41":286,"_31":287,"_29":288,"_155":-5,"_39":40,"_38":289,"_157":57,"_36":290,"_13":291,"_33":20,"_34":292,"_23":24,"_162":-5,"_26":293},{"_41":278,"_31":279,"_29":280,"_155":-5,"_39":40,"_38":281,"_157":24,"_36":282,"_13":283,"_33":20,"_34":284,"_23":24,"_162":-5,"_26":285},{"_41":271,"_31":272,"_29":273,"_155":-5,"_39":40,"_38":274,"_157":57,"_36":275,"_13":231,"_33":160,"_34":276,"_23":24,"_162":-5,"_26":277},{"_41":264,"_31":265,"_29":266,"_155":-5,"_39":40,"_38":267,"_157":57,"_36":268,"_13":231,"_33":160,"_34":269,"_23":24,"_162":-5,"_26":270},{"_41":256,"_31":257,"_29":258,"_155":-5,"_39":40,"_38":259,"_157":57,"_36":260,"_13":261,"_33":160,"_34":262,"_23":24,"_162":-5,"_26":263},{"_41":249,"_31":250,"_29":251,"_155":-5,"_39":40,"_38":252,"_157":57,"_36":253,"_13":184,"_33":160,"_34":254,"_23":24,"_162":-5,"_26":255},{"_41":241,"_31":242,"_29":243,"_155":-5,"_39":40,"_38":244,"_157":24,"_36":245,"_13":246,"_33":160,"_34":247,"_23":24,"_162":-5,"_26":248},{"_41":234,"_31":235,"_29":236,"_155":-5,"_39":40,"_38":237,"_157":57,"_36":238,"_13":223,"_33":160,"_34":239,"_23":24,"_162":-5,"_26":240},{"_41":226,"_31":227,"_29":228,"_155":-5,"_39":40,"_38":229,"_157":57,"_36":230,"_13":231,"_33":160,"_34":232,"_23":24,"_162":-5,"_26":233},{"_41":218,"_31":219,"_29":220,"_155":-5,"_39":40,"_38":221,"_157":24,"_36":222,"_13":223,"_33":20,"_34":224,"_23":24,"_162":-5,"_26":225},{"_41":210,"_31":211,"_29":212,"_155":-5,"_39":40,"_38":213,"_157":24,"_36":214,"_13":215,"_33":160,"_34":216,"_23":24,"_162":-5,"_26":217},{"_41":203,"_31":204,"_29":205,"_155":-5,"_39":40,"_38":206,"_157":57,"_36":207,"_13":61,"_33":160,"_34":208,"_23":24,"_162":-5,"_26":209},{"_41":195,"_31":196,"_29":197,"_155":-5,"_39":40,"_38":198,"_157":24,"_36":199,"_13":200,"_33":160,"_34":201,"_23":24,"_162":-5,"_26":202},{"_41":187,"_31":188,"_29":55,"_155":-5,"_39":40,"_38":189,"_157":57,"_36":190,"_13":191,"_33":192,"_34":193,"_23":24,"_162":-5,"_26":194},{"_41":179,"_31":180,"_29":181,"_155":-5,"_39":40,"_38":182,"_157":57,"_36":183,"_13":184,"_33":160,"_34":185,"_23":24,"_162":-5,"_26":186},{"_41":171,"_31":172,"_29":173,"_155":-5,"_39":40,"_38":174,"_157":57,"_36":175,"_13":176,"_33":160,"_34":177,"_23":24,"_162":-5,"_26":178},{"_41":164,"_31":165,"_29":166,"_155":-5,"_39":40,"_38":167,"_157":24,"_36":168,"_13":61,"_33":160,"_34":169,"_23":24,"_162":-5,"_26":170},{"_41":152,"_31":153,"_29":154,"_155":-5,"_39":40,"_38":156,"_157":24,"_36":158,"_13":159,"_33":160,"_34":161,"_23":24,"_162":-5,"_26":163},"084ddf7d-6dbf-4efc-9264-0a3ed820f3d1","ui.tsx","fca19e20-7b48-11f1-8cf9-1607ee4eb77e","parentId",278,"latest",["D",1784060920570],34,"script","/** @jsxImportSource npm:hono@4.6.14/jsx */\nimport type { FC, PropsWithChildren } from \"npm:hono@4.6.14/jsx\";\nimport type { IssueStatus, Label, StateReason } from \"./db.ts\";\nimport { T } from \"./theme.ts\";\n\nexport const FIELD =\n `bg-[${T.surface}] border border-[${T.border}] rounded-md min-h-10 px-3.5 text-sm font-medium text-[${T.text}] focus:outline-none focus:border-[${T.link}]`;\nconst BUTTON =\n \"inline-flex items-center gap-1.5 rounded-md min-h-10 px-3.5 text-sm font-medium cursor-pointer no-underline\";\nconst VARIANTS = {\n solid:\n `bg-[${T.accent}] border border-[${T.accent}] text-white hover:brightness-110`,\n ghost:\n `bg-transparent border border-[${T.accent}] text-[${T.text}] hover:brightness-110`,\n danger:\n `bg-transparent border border-[${T.danger}] text-[${T.danger}] hover:bg-[${T.danger}] hover:text-white`,\n} as const;\n\nexport const STATUS_LABELS: Record = {\n open: \"Open\",\n closed: \"Closed\",\n};\nexport const STATE_REASON_LABELS: Record, string> = {\n completed: \"Completed\",\n not_planned: \"Not planned\",\n duplicate: \"Duplicate\",\n reopened: \"Reopened\",\n};\n\nexport const Card: FC> = ({\n children,\n class: cls,\n}) => (\n \n {children}\n \n);\n\nexport const Button: FC<\n PropsWithChildren<{\n variant?: keyof typeof VARIANTS;\n href?: string;\n type?: \"button\" | \"submit\";\n class?: string;\n name?: string;\n value?: string;\n form?: string;\n }>\n> = ({\n variant = \"solid\",\n href,\n type = \"button\",\n class: cls,\n name,\n value,\n form,\n children,\n}) => {\n const classes = `${BUTTON} ${VARIANTS[variant]} ${cls ?? \"\"}`;\n return href\n ? (\n \n {children}\n \n )\n : (\n \n {children}\n \n );\n};\n\nexport const Select: FC<\n PropsWithChildren<{ name: string; id?: string; class?: string }>\n> = ({ name, id, class: cls, children }) => (\n \n);\n\nexport const Banner: FC<{ kind: \"ok\" | \"err\"; msg: string }> = ({\n kind,\n msg,\n}) => (\n \n {msg}\n \n);\n\nexport const StatusBadge: FC<{ status: IssueStatus; reason?: StateReason }> = ({\n status,\n reason,\n}) => (\n \n {STATUS_LABELS[status]}\n {reason ? ` · ${STATE_REASON_LABELS[reason]}` : \"\"}\n \n);\n\nexport const LabelTag: FC<{ label: Label }> = ({ label }) => (\n \n {label.name}\n \n);\n","label",[153],"475f9406-f7d1-4bd0-bbfd-8ffa2b6974b4","theme.ts","743531d4-7fba-11f1-b433-1607ee4eb77e",260,["D",1784057421314],"/**\n * Single source of truth for the recurring dark-palette hex values used\n * across layout.tsx, ui.tsx, and components.tsx. Presentation-only —\n * no local imports, so importing this file can never create a cycle.\n *\n * Only colors that genuinely recur 2+ times across those files live here.\n * One-off tints (banner ok/err colors, dynamic label colors, Tailwind\n * named colors like `blue-500`) stay inline where they're used.\n */\nexport const T = {\n /** Page background. */\n bg: \"#0f1115\",\n /** Header / card background. */\n panel: \"#181b22\",\n /** Inputs, table rows, nested surfaces. */\n surface: \"#1f232c\",\n /** Borders and dividers. */\n border: \"#2a2f3a\",\n /** Primary text. */\n text: \"#e6e9ef\",\n /** Secondary / muted text. */\n muted: \"#8b93a3\",\n /** Links and focus rings. */\n link: \"#6ea8fe\",\n /** Primary accent (solid buttons). */\n accent: \"#3d7bf0\",\n /** Danger / destructive actions. */\n danger: \"#f06e7b\",\n} as const;\n",[165],"06a3a637-e081-4666-a2b1-479fa57ef458","test_sqlite.ts","2bb2ce86-7c0d-11f1-9a68-1607ee4eb77e",220,["D",1784052697980],3,"import { DatabaseSync } from \"node:sqlite\";\n\nexport interface TestResultSet {\n columns: string[];\n rows: Record[];\n rowsAffected: number;\n lastInsertRowid: bigint | undefined;\n}\n\nexport function createTestSqlite() {\n const database = new DatabaseSync(\":memory:\");\n database.exec(\"PRAGMA foreign_keys = ON\");\n\n const execute = (\n statement: string | { sql: string; args?: unknown[] },\n ): Promise => {\n try {\n const sql = typeof statement === \"string\" ? statement : statement.sql;\n const args = typeof statement === \"string\" ? [] : (statement.args ?? []);\n const prepared = database.prepare(sql);\n if (/^\\s*(SELECT|PRAGMA|WITH)\\b/i.test(sql)) {\n const rows = prepared.all(...(args as never[])) as Record<\n string,\n unknown\n >[];\n return Promise.resolve({\n columns: rows[0] ? Object.keys(rows[0]) : [],\n rows,\n rowsAffected: 0,\n lastInsertRowid: undefined,\n });\n }\n const result = prepared.run(...(args as never[]));\n return Promise.resolve({\n columns: [],\n rows: [],\n rowsAffected: Number(result.changes),\n lastInsertRowid: BigInt(result.lastInsertRowid),\n });\n } catch (error) {\n return Promise.reject(error);\n }\n };\n\n return {\n database,\n execute,\n /**\n * Mirror the libsql `transaction(\"write\")` contract on top of node:sqlite:\n * `BEGIN IMMEDIATE` opens an exclusive write transaction, statements run\n * sequentially on the single in-memory connection, and `commit`/`rollback`\n * close it. This is the same atomic-write contract `db.ts` drives in\n * production, so the store tests exercise the real transaction path.\n */\n transaction(_mode?: \"write\" | \"read\" | \"deferred\") {\n database.exec(\"BEGIN IMMEDIATE\");\n let settled = false;\n const finish = (verb: \"COMMIT\" | \"ROLLBACK\") => {\n if (settled) return Promise.resolve();\n settled = true;\n database.exec(verb);\n return Promise.resolve();\n };\n return Promise.resolve({\n execute,\n commit: () => finish(\"COMMIT\"),\n rollback: () => finish(\"ROLLBACK\"),\n });\n },\n };\n}\n",[172],"8d2480e3-0dfc-4ba9-ba40-4da9d6b62915","mod.ts","d1e3fc5c-7b3c-11f1-af1c-1607ee4eb77e",224,["D",1784052697990],13,"export { default, issueTracker, type IssueTrackerOptions } from \"./app.tsx\";\n",[180],"b7ee6e4d-e03e-49f9-b6a3-e9b3852a593e","main.ts",214,["D",1783790091112],11,"http","import { issueTracker } from \"./mod.ts\";\n\n/**\n * This val's own issue tracker — manages THIS val's scoped SQLite database.\n *\n * To add issues to a DIFFERENT val, import the tracker into that val:\n *\n * import { issueTracker } from \"https://esm.town/v/nbbaier/val-issue-tracker/mod.ts\";\n * export default issueTracker({ owner: [\"nbbaier\"] });\n *\n * Because scoped SQLite is bound to the running val, the imported tracker\n * reads/writes the host val's database automatically — no per-val config needed.\n */\nexport default issueTracker({});\n",[188],"a8da133e-f3ec-4798-9ac8-7e818889dd8b","layout.tsx","fd6015ee-7b48-11f1-bafe-1607ee4eb77e",265,["D",1784058461137],7,"/** @jsxImportSource npm:hono@4.6.14/jsx */\nimport type { FC, PropsWithChildren } from \"npm:hono@4.6.14/jsx\";\nimport { T } from \"./theme.ts\";\n\nconst TAB =\n `inline-flex items-center px-3 py-1.5 border-b-2 border-transparent text-sm no-underline`;\nconst TAB_ACTIVE = `text-[${T.text}] font-semibold border-[${T.accent}]`;\nconst TAB_IDLE = `text-[${T.muted}] hover:text-[${T.text}]`;\n\n/** Small avatar + handle chip for the top bar's right edge. */\nconst UserChip: FC<{ user: string }> = ({ user }) => (\n \n \n {user.charAt(0) || \"?\"}\n \n @{user || \"?\"}\n \n);\n\nexport const Layout: FC<\n PropsWithChildren<{\n title: string;\n user?: string | null;\n auth?: boolean;\n /** Login location supplied by the owning auth surface, when available. */\n login?: string | null;\n /** Mount prefix for internal links; \"\" standalone. /auth/* stays\n * origin-level in both modes, so those links never take it. */\n base?: string;\n /** Which top-bar tab is the current surface. */\n active?: \"issues\" | \"labels\";\n }>\n> = ({\n title,\n user,\n auth = true,\n login,\n base = \"\",\n active,\n children,\n}) => {\n const signedIn = user !== null && user !== undefined;\n const loginHref = login === undefined ? (auth ? \"/auth/login\" : null) : login;\n const chip = signedIn ? : null;\n const logoutForm = (\n

\n \n Log out\n \n \n );\n const loginLink = loginHref\n ? (\n \n Log in\n \n )\n : null;\n\n return (\n \n \n \n \n {title}\n \n \n\n",[],[315,497],"0624324c-15a1-4656-b4f5-0e2e312f15c2","flow.svg","b35d6c26-7fb7-11f1-851e-1607ee4eb77e",241,["D",1784056238995],"\n",[],[315,505],["D",1784056238376],[373,374,375,376,377,378],[315],"a7d6b8dd-1925-4e52-8b1a-7519e5abc73e","issue-tracker-valtown.md","4e874dca-7be4-11f1-973a-1607ee4eb77e",199,["D",1783711960586],2,"# Issue tracker: val-issue-tracker (JSON API)\n\nUse the tracker's JSON API for agent and script operations; do not scrape HTML.\n\n**Tracker URL**: `` (for example `https://username-myval.web.val.run`)\n\n**Auth**: reads are public. Writes require\n`Authorization: Bearer `. Each write may include `actor`,\na Val Town handle; omitted actors default to `agent`. Actor provenance is stored\nonly in the append-only events log.\n\n## Response shapes\n\nEvery response is JSON. Successful responses are either a single object, an\narray, or a small acknowledgement object (`{\"deleted\": id}` /\n`{\"updated\": id}`); error responses always have the shape:\n\n```json\n{ \"error\": \"human-readable message\" }\n```\n\n### Label\n\n```ts\n{\n id: number;\n name: string;\n color: string; // six lowercase hex characters, no leading \"#\"\n created_at: number; // ms since epoch\n updated_at: number;\n}\n```\n\n### IssueReference\n\nThe compact shape used inside `blockers` and `blocks`.\n\n```ts\n{\n id: number;\n title: string;\n status: \"open\" | \"closed\";\n state_reason: \"completed\" | \"not_planned\" | \"duplicate\" | \"reopened\" | null;\n}\n```\n\n### Issue\n\n```ts\n{\n id: number;\n title: string;\n body: string; // markdown, verbatim (not trimmed)\n status: \"open\" | \"closed\";\n state_reason: \"completed\" | \"not_planned\" | \"duplicate\" | \"reopened\" | null;\n created_at: number;\n updated_at: number; // last activity: own edits, comments, or association changes\n creator: string | null; // Val Town handle, derived from the issue's creation event\n labels: Label[];\n assignees: string[]; // Val Town handles, no \"@\" prefix\n blockers: IssueReference[];\n blocks: IssueReference[];\n blocked: boolean; // true iff at least one blocker is still \"open\"\n}\n```\n\n`GET /api/issues/:id` returns an `Issue` plus a `comments` field\n(`comments: Comment[]`); no other endpoint includes `comments`.\n\n### Comment\n\n```ts\n{\n id: number;\n issue_id: number;\n body: string; // markdown, verbatim\n created_at: number;\n updated_at: number;\n author: string | null; // Val Town handle, derived from the comment's creation event\n}\n```\n\n### Event\n\n```ts\n{\n id: number;\n event_type:\n | \"issue.created\" | \"issue.updated\" | \"issue.deleted\"\n | \"comment.created\" | \"comment.updated\" | \"comment.deleted\"\n | \"label.created\" | \"label.updated\" | \"label.deleted\";\n entity_id: number; // the issue/comment/label id the event is about\n actor: string;\n data: unknown; // grammar below\n event_timestamp: number;\n}\n```\n\n`GET /api/issues/:id/events` returns `Event[]` in append order.\n\n## Event data grammar\n\nEvents are the source of truth for provenance and history; live tables hold only\ncurrent state.\n\n- **Boundary events (`*.created`, `*.deleted`) snapshot full state.** The `data`\n field is the entity's complete state at that moment — a hard-deleted row\n leaves a full tombstone:\n - `issue.created` / `issue.deleted` data:\n `{id, title, body, status, state_reason, created_at, updated_at}`\n - `comment.created` / `comment.deleted` data:\n `{id, issue_id, body, created_at, updated_at}` (no `author` — that is always\n derived from the surrounding event, never stored in the payload)\n - `label.created` / `label.deleted` data:\n `{id, name, color, created_at, updated_at}`\n- **`*.updated` events carry a single field delta:**\n `{update_target, from, to}`.\n - For `issue.updated`, `update_target` is one of `title`, `body`, `status`,\n `state_reason`, `label`, `assignee`, `blocks`, `blocked_by`. Associations\n (`label`, `assignee`, `blocks`, `blocked_by`) use **`null ↔ value`**\n (`from: null` = added, `to: null` = removed). A block edge writes exactly\n one event, on the acting issue (the one named in the endpoint path).\n - For `comment.updated`, `update_target` is `\"body\"`.\n - For `label.updated`, `update_target` is `\"name\"` or `\"color\"`.\n - One event per changed field: closing an issue with a new reason emits two\n `issue.updated` events (`status` and `state_reason`), sharing one actor and\n timestamp.\n\n## Status codes\n\n| Status | Meaning |\n| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `200` | Read succeeded, or a mutation applied and the endpoint returns the resulting state. |\n| `201` | An issue, comment, or label was created. |\n| `400` | The request is malformed: invalid `:id`, invalid `status` filter, invalid close `reason`, invalid label `color`, a missing required scalar field (`title`; `name`/`color`; comment `body`), or a collection field (`label_ids`, `add`, `remove`, `assignees`) that isn't shaped as required — see below. |\n| `401` | A write was attempted with a missing or incorrect bearer token. |\n| `403` | A write was attempted but `ISSUE_TRACKER_API_KEY` isn't configured, so writes are disabled entirely. |\n| `404` | The issue, comment, or label named by `:id` — or referenced by an ID inside `label_ids`/`add`/`remove` — does not exist. |\n| `409` | The write conflicts with an existing invariant: a blocking edge would create a cycle (including a self-edge), or a label `name` collides with an existing label. |\n\n## Strict collection validation\n\n`label_ids`, and the `add`/`remove` fields on the labels and blocks/blocked-by\nendpoints, are validated as a whole, not filtered element by element:\n\n- **Absent** — treated as an empty operation (no IDs added or removed).\n- **Present** — must be an array where every element is a positive integer\n (`Number.isInteger(x) && x > 0`). Any other shape (not an array, a\n non-integer, zero, a negative number, a string, etc.) rejects the entire\n request with `400`; nothing is applied.\n- Each ID that passes shape validation must still reference an existing label or\n issue, or the request fails with `404`.\n\n`assignees`, and the `add`/`remove` fields on the assignees endpoint, follow the\nsame absent-is-empty / present-is-all-or-nothing rule, but for handles:\n\n- **Present** — must be an array of non-empty strings after trimming and\n stripping a leading `@`. Any other shape rejects the request with `400`.\n- Handles are not entities (no lookup table), so there is no `404` for an\n unrecognized assignee — any well-shaped handle is accepted.\n\n## Endpoints\n\n| Method and path | Body / query | Success |\n| --------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `GET /api/issues` | `?status=open\\|closed&label=&assignee=&search=` | `200` `Issue[]`. `400` if `status` is present and not `open`/`closed`. |\n| `POST /api/issues` | `{title, body?, label_ids?: number[], assignees?: string[], actor?}` | `201` `Issue`. `400` missing `title` or malformed `label_ids`/`assignees`. `404` if a `label_ids` entry doesn't exist. |\n| `GET /api/issues/:id` | — | `200` `Issue & {comments: Comment[]}`. `400` invalid id. `404` missing issue. |\n| `PATCH /api/issues/:id` | `{title?, body?, actor?}` | `200` updated `Issue`. `400` invalid id. `404` missing issue. |\n| `DELETE /api/issues/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing issue. |\n| `POST /api/issues/:id/close` | `{reason?: \"completed\" \\| \"not_planned\" \\| \"duplicate\", comment?, actor?}` | `200` updated `Issue`; reason defaults to `completed`. `400` invalid id/reason. `404` missing issue. |\n| `POST /api/issues/:id/reopen` | `{actor?}` | `200` updated `Issue` with `state_reason: \"reopened\"`. `400` invalid id. `404` missing issue. |\n| `POST /api/issues/:id/labels` | `{add?: number[], remove?: number[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue or a missing label id. |\n| `POST /api/issues/:id/assignees` | `{add?: string[], remove?: string[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue. |\n| `POST /api/issues/:id/blocks` | `{add?: number[], remove?: number[], actor?}` | `200` updated `Issue`. `400` invalid id or malformed `add`/`remove`. `404` missing issue or referenced issue id. `409` cycle or self-edge. |\n| `POST /api/issues/:id/blocked-by` | `{add?: number[], remove?: number[], actor?}` | Same as `/blocks`, opposite edge direction. |\n| `POST /api/issues/:id/comments` | `{body, actor?}` | `201` `Comment`. `400` invalid id or missing `body`. `404` missing issue. |\n| `PATCH /api/comments/:id` | `{body, actor?}` | `200` `{updated: id}`. `400` invalid id or missing `body`. `404` missing comment. |\n| `DELETE /api/comments/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing comment. |\n| `GET /api/issues/:id/events` | — | `200` `Event[]` in append order. `400` invalid id. `404` missing issue. |\n| `GET /api/labels` | — | `200` `Label[]`. |\n| `POST /api/labels` | `{name, color, actor?}` | `201` `Label` (`color` is hex, with or without `#`). `400` missing `name`/`color` or invalid `color`. `409` `name` already in use. |\n| `PATCH /api/labels/:id` | `{name?, color?, actor?}` | `200` updated `Label`. `400` invalid id or `color`. `404` missing label. `409` renaming to an in-use `name`. |\n| `DELETE /api/labels/:id` | `{actor?}` | `200` `{deleted: id}`. `400` invalid id. `404` missing label. |\n\nAll write routes additionally return `401` for a missing/incorrect bearer token,\nand `403` if `ISSUE_TRACKER_API_KEY` is unset — checked before any body or id\nvalidation.\n\n## Triage labels\n\nLabels are curated entities, not free-text arrays. Before applying workflow\nlabels such as `needs-triage`, create each one once with `POST /api/labels`,\nretain its ID, then send that ID to the issue-label endpoint. The product's\nfresh-install defaults are `bug`, `enhancement`, `documentation`, `question`,\nand `duplicate`.\n\n## curl examples\n\n```bash\nTRACKER=https://your-handle-your-val.web.val.run\nKEY=...\n\n# Discover label IDs\ncurl -s \"$TRACKER/api/labels\"\n\n# Create with curated labels and multiple assignees\ncurl -s -X POST \"$TRACKER/api/issues\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Fix flaky test\",\"body\":\"Observed in CI\",\"label_ids\":[1],\"assignees\":[\"alice\"],\"actor\":\"alice\"}'\n\n# Close as deliberately not planned\ncurl -s -X POST \"$TRACKER/api/issues/12/close\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"not_planned\",\"comment\":\"Superseded by #15.\",\"actor\":\"alice\"}'\n\n# Reopen\ncurl -s -X POST \"$TRACKER/api/issues/12/reopen\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"actor\":\"alice\"}'\n\n# Declare that #12 blocks #15\ncurl -s -X POST \"$TRACKER/api/issues/12/blocks\" \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"add\":[15],\"actor\":\"alice\"}'\n```\n",[],[322,516],"209f927c-480f-4f66-8f57-ecc131f50714","backlog.md","eea1bf8a-7bf2-11f1-975e-1607ee4eb77e",173,["D",1783653142692],"# Backlog — deferred wants\n\nThings wanted eventually, not now. Not commitments; parking lot.\n\n- **Clickable user handles.** Wherever a user handle is displayed (creator,\n comment author, assignee), render it as a link to that user's Val Town\n profile. Purely a rendering concern — the data model just stores the handle.\n (See [[User]] in CONTEXT.md.)\n- **Markdown rendering.** Issue bodies and comment bodies are stored as\n markdown; rendering them to HTML is a later concern.\n",[],[322,525],"0f39a161-6c79-4dab-9fbc-d3a2a3ec0bc0","tickets.md","eeb0130a-7bf2-11f1-8022-1607ee4eb77e","ee67d8e2-7bf2-11f1-b0f6-1607ee4eb77e",175,["D",1783653142898],"# Tickets: Richer data model for val-issue-tracker\n\nTracer-bullet tickets implementing the richer data model. Source spec:\n`docs/issues/richer-data-model/PRD.md`. Governed by `CONTEXT.md` + ADRs\n0001–0004.\n\nAll tickets are `ready-for-agent` — agent-grabbable by construction.\n\n## Implementation checklist\n\n- [x] Ticket 1 — core schema reshape and issue lifecycle\n- [x] Ticket 2 — append-only events and lifecycle provenance\n- [x] Ticket 3 — labels, assignees, blocking, comments, events, and touch rules\n- [x] Ticket 4 — idempotent old-schema migration\n- [x] Ticket 5 — final JSON API convention, consumer cleanup, and verification\n\nWork the **frontier**: any ticket whose blockers are all done. Order here is\ndependency order (blockers first): 1 → 2 → 3 → then 4 and 5 in parallel.\n\n> Migration caveat: tickets 1–3 are correct against _fresh_ databases. The ~3\n> existing deployments are only safe to run once ticket 4 (migration) lands,\n> since `initSchema` runs against live data every request. Deploy the set at the\n> end.\n\n## 1. Core schema reshape + issue lifecycle\n\nStatus: ready-for-agent\n\n**What to build:** Fresh-install issue schema on the new model — priority\nremoved entirely; `status` collapses to `open`/`closed`; a nullable\n`state_reason` (`completed`/`not_planned`/`duplicate`/`reopened`) guarded by a\n`CHECK` constraint against status; the issue body field renamed from\n`description` to `body`. The create / close / reopen operations auto-manage\n`state_reason` (create → null; close → chosen reason, default `completed`;\nreopen → `reopened`). The JSON API and HTML UI are reconciled to the new `Issue`\nshape, and the schema knowledge those two consumers currently duplicate\n(status/priority constants, label parse/serialize) is pulled into the\ndata-access layer as a prefactor so later tickets change one place. No migration\nof existing data in this ticket. _Demoable: create an issue, close it as\nnot_planned, reopen it — through both the API and the UI._\n\n**Blocked by:** None — can start immediately.\n\n## 2. Events log foundation + issue lifecycle events\n\nStatus: ready-for-agent\n\n**What to build:** The single append-only events table (`id`, `event_type`,\n`entity_id`, `actor`, `data`, `event_timestamp`) and the emit helper, wired into\nthe issue lifecycle from ticket 1. `*.created` and `*.deleted` carry full state\nsnapshots; `*.updated` carries `{ update_target, from, to }`. One event per\nchanged field, so closing emits two events (`status` and `state_reason`) sharing\nan actor and timestamp. _Demoable: close an issue and observe two events with\nthe acting handle and correct payloads._\n\n**Blocked by:** 1\n\n## 3. Associations: labels + assignees + blocking\n\nStatus: ready-for-agent\n\n**What to build:** All three issue relationships, end-to-end (schema +\noperations + API\n\n- UI + events + touch rule):\n\n* **Labels** — a curated Label entity (`name`, `color`), applied via a bare\n issue↔label join; a default set (`bug`, `enhancement`, `documentation`,\n `question`, `duplicate`) seeded exactly once at table creation and never\n re-seeded; apply/remove; label rename/recolour/delete (deleting an in-use\n label cascades its join rows away).\n* **Assignees** — a set of Val Town users via a bare issue↔handle join;\n add/remove; an \"assigned to me\" query.\n* **Blocking** — a directed `blocker → blocked` edge stored once; insert\n rejected if the target can already reach the source (strict DAG — self,\n reciprocal, and longer cycles all refused); remove; \"blocked\" derived (blocked\n while any blocker is still open) and never stored, and never gating close.\n\nEvery mutation emits its events — label ops as `label.*` plus `issue.updated`\nwith `update_target: label` using `null ↔ value`; assignee and block changes as\n`issue.updated` with `update_target` ∈ {assignee, blocks, blocked_by},\n`null ↔ value`; a block edge writes one event on the acting issue. Every\nassociation change also touches the parent issue's `updated_at`.\n\n_(Largest ticket — if it overflows a single context window at execution time,\nsplit back into labels / assignees / blocking, each blocked by 1 and 2.)_\n\n**Blocked by:** 1, 2\n\n## 4. Migration for existing deployments\n\nStatus: ready-for-agent\n\n**What to build:** One idempotent migration routine (living in the schema-init\npath, safe to run every request) that brings the ~3 existing deployments onto\nthe final schema: remap any `in_progress` issue to `open`; drop priority; expose\nthe old `description` as `body`; lift each existing JSON `labels` array into the\nLabel entities and issue↔label join (creating labels as needed); move any\nexisting single `assignee` into the assignee join; and backfill a synthetic\n`*.created` event (and any required state) for existing rows so no entity is\nleft without provenance. Running it twice is a no-op.\n\n**Blocked by:** 1, 2, 3\n\n## 5. Rewrite JSON API convention doc + final cleanup\n\nStatus: ready-for-agent\n\n**What to build:** Rewrite `docs/issue-tracker-valtown.md` to the new schema and\nendpoint surface (no priority, two statuses, `state_reason` on close/reopen, and\nthe label / assignee / block operations), replacing the outdated convention it\ndocuments today. Remove any remaining old-schema constants or dead code paths in\nthe consumers. Done last so the doc describes the final API exactly once.\n\n**Blocked by:** 3\n",[],[322,541,542,533],"issues","richer-data-model","a737b999-a091-40e2-b4b3-e3065d4580e1","certification.md","1d471d5a-7c96-11f1-a281-1607ee4eb77e",299,["D",1784073502601],"# Certification: richer-data-model remediation pass\n\nDate: 2026-07-10 Verdict: **certified complete** (independent recertification\naudit)\n\nAfter the five implementation tickets in `tickets.md` landed, a remediation pass\nran as five one-shot agent prompts (formerly in `agent-prompts/`, deleted after\nthis certification). What each fixed:\n\n1. **SQLite transaction contract** — `db.ts` drives every multi-statement write\n through `client.transaction(\"write\")` with explicit commit/rollback, never\n top-level `batch()`. The resolved adapter\n (`npm:@tursodatabase/serverless@1.2.3/compat`) was read at source and its\n top-level `batch()` confirmed broken for this purpose: it ignores the mode\n argument and drops bound args. Proven by tests: a batch-throwing client,\n forced mid-transaction failure rollback, and entity-ID (not event-ID) return\n values.\n2. **Comment UI** — the comment edit control is a `

` that round-trips\n   multiline markdown through the real Hono form routes; bodies render as\n   escaped JSX text with `whitespace-pre-wrap` (no HTML rendering). Control\n   visibility fixed via a maintainer-only `canModerateComments` prop on\n   `IssueDetailPage`: maintainers and the comment author see edit/delete\n   controls; a non-author issue creator does not. Server-side checks remain the\n   enforcement layer and the UI mirrors them exactly.\n3. **API/docs parity** — strict all-or-nothing validation for collection fields\n   (`label_ids`/`add`/`remove`/`assignees`: absent = empty operation,\n   present-but-malformed = 400); 400 for an invalid `status` filter; 404\n   existence guards on every mutation route; a small typed `HttpError`\n   (400/404/409) in `db.ts` replacing the old map-everything-to-409 handler;\n   `docs/issue-tracker-valtown.md` rewritten with complete response shapes, the\n   event-data grammar, the `{\"error\": \"...\"}` convention, a status-code table,\n   and exact per-route responses matching `api.ts` route-by-route.\n4. **Check policy** — repository reality uses Deno's built-in formatter via\n   `deno.json`; `.vt/` and `.claude/` are excluded from formatting; canonical\n   commands are the `deno.json` tasks `fmt` / `lint` / `typecheck` / `test` /\n   `check`; README Development documents the same commands, and `check` uses the\n   non-mutating `deno fmt --check` gate.\n5. **Recertification** — independent audit rebuilt the requirement matrix for\n   all five tickets against the PRD, re-ran all checks (21/21 tests), compared\n   every API route against the convention doc (18 route/status combinations),\n   and repeated the stale-schema scan: no live use of priority, `in_progress`,\n   `description`, JSON-label storage, single-assignee storage, `*_by` columns,\n   or a stored comment `author` column (`Comment.author` is derived from\n   `comment.created` events via JOIN, per ADR 0003/0004). The only old- schema\n   references are the migration reader in `db.ts` and legacy-fixture SQL in\n   `db_test.ts`, by design.\n\n## Caveats\n\n- Nothing was deployed. The adapter-contract proof is static (reading the\n  resolved dependency's source), not a live round-trip against Val Town's scoped\n  SQLite. Live proof requires deploying and exercising one transactional write.\n",[],[322,541,542,544],"85c72af1-cc92-4979-a7a5-bac2e38e7689","PRD.md","eebd1596-7bf2-11f1-ab8e-1607ee4eb77e",174,["D",1783653142818],"# Spec: Richer data model for val-issue-tracker\n\nStatus: ready-for-agent\n\n> Synthesised from a grilling + domain-modeling session. Vocabulary follows\n> `CONTEXT.md`; decisions are governed by ADRs 0001–0004. This is a breaking\n> schema change to the tracker's own data model, plus the migration to get the\n> ~3 existing deployments onto it.\n\n## Problem Statement\n\nThe tracker's current data model carries fields the maintainer doesn't use and\ncan't represent the relationships they actually want. Priority is dead weight.\nStatus has a middle `in_progress` state that isn't wanted, yet there's no way to\nsay _why_ something was closed (done vs. abandoned). Labels are a JSON-array\nstring matched with `LIKE`, so they can't have colour, be renamed in one place,\nor be queried cleanly. There's no way to express that one issue blocks another.\nThere is no history: once a label is removed or an assignee dropped, the fact\nthat it was ever there is gone, and there's no record of who changed what. The\nmaintainer wants a GitHub-flavoured model that captures these relationships and\na full audit trail.\n\n## Solution\n\nReshape the tracker's schema to mirror GitHub's issue model where it earns its\nkeep, and add first-class structure for the things the maintainer actually uses:\n\n- Drop priority entirely and collapse status to `open` / `closed`, with a\n  nullable `state_reason` (`completed` / `not_planned` / `duplicate` /\n  `reopened`) carrying the nuance — so \"closed as done\" and \"closed as not\n  planned\" are distinguishable.\n- Promote labels from a JSON string to curated **Label** entities (name +\n  colour), applied to issues through a join, seeded with a small default set on\n  first install.\n- Make assignees a _set_ of Val Town users via a join, instead of a single\n  string.\n- Add directed **blocking relationships** between issues, kept as a strict DAG,\n  with \"blocked\" derived (an issue is blocked while any blocker is still open).\n- Record every change in a single append-only **events** log — the source of\n  truth for provenance (\"who did what, when\") and full state history, from which\n  auditability is derived. Live tables hold only current state.\n- Treat issue and comment bodies as markdown (a rendering contract; no storage\n  change).\n\nIdentity throughout is the Val Town handle — there is no local users table.\n\n## User Stories\n\n1. As a maintainer, I want priority removed from issues, so that the model\n   reflects that I never triage by priority.\n2. As a maintainer, I want status to be exactly `open` or `closed`, so that\n   there is no unwanted intermediate state to maintain.\n3. As a maintainer, I want to close an issue as `completed`, so that I can\n   record that the work was actually done.\n4. As a maintainer, I want to close an issue as `not_planned`, so that I can\n   record that I abandoned it rather than finished it.\n5. As a maintainer, I want to close an issue as `duplicate`, so that I can\n   record that it was already tracked elsewhere.\n6. As a maintainer, I want reopening an issue to mark its reason as `reopened`,\n   so that a reopened issue is distinguishable from one that was never closed.\n7. As a maintainer, I want the system to refuse an incoherent status/reason pair\n   (e.g. open + completed), so that the data can never represent an impossible\n   state.\n8. As a maintainer, I want `state_reason` to be set automatically by the\n   close/reopen/create actions, so that I can't forget to keep it consistent\n   with status.\n9. As a maintainer, I want labels to be real entities with names and colours, so\n   that I can see and manage a consistent taxonomy.\n10. As a maintainer, I want to apply an existing label to an issue by picking\n    it, so that typos can't spawn phantom labels.\n11. As a maintainer, I want to remove a label from an issue, so that the tag set\n    stays accurate.\n12. As a maintainer, I want a fresh install to come with a default set of labels\n    (`bug`, `enhancement`, `documentation`, `question`, `duplicate`), so that\n    the tracker is usable immediately.\n13. As a maintainer, I want labels I delete to stay deleted across restarts, so\n    that the default set doesn't resurrect itself on the next request.\n14. As a maintainer, I want to delete a label that is currently applied to\n    issues, so that retiring a tag just removes it everywhere.\n15. As a maintainer, I want to rename or recolour a label in one place, so that\n    every issue carrying it updates at once.\n16. As a maintainer, I want an issue to have zero or more assignees, so that\n    more than one Val Town user can own it.\n17. As a maintainer, I want to add and remove assignees on an issue, so that\n    ownership can change over time.\n18. As a maintainer, I want to ask \"what is assigned to me?\", so that I can find\n    my work without scanning every issue.\n19. As a maintainer, I want to declare that one issue blocks another, so that I\n    can express dependencies.\n20. As a maintainer, I want to view an issue's blockers and the issues it\n    blocks, so that I understand its dependency context from either direction.\n21. As a maintainer, I want an issue to show as blocked while any of its\n    blockers is still open, so that blocked-ness is always accurate without my\n    maintaining a flag.\n22. As a maintainer, I want closing a blocker to automatically unblock its\n    dependents, so that the state stays correct for free.\n23. As a maintainer, I want to still be able to close a blocked issue, so that\n    being blocked is informational and never traps me.\n24. As a maintainer, I want the system to reject an issue blocking itself, so\n    that nonsensical edges can't exist.\n25. As a maintainer, I want the system to reject any edge that would create a\n    cycle (direct or longer), so that the dependency graph stays a coherent DAG.\n26. As a maintainer, I want to remove a blocking relationship, so that I can\n    correct a dependency I no longer want.\n27. As a maintainer, I want issue and comment bodies treated as markdown, so\n    that formatting is preserved for later rendering.\n28. As a maintainer, I want to edit an issue's title and body, so that I can\n    correct or refine it after creation.\n29. As a maintainer, I want to edit a comment, so that I can fix mistakes in my\n    notes.\n30. As a maintainer, I want to delete a comment, so that I can remove notes that\n    no longer belong.\n31. As an auditor, I want every create, update, and delete recorded as an event\n    with the actor and timestamp, so that I can reconstruct who changed what and\n    when.\n32. As an auditor, I want each field change recorded with its before and after\n    value, so that I can see the full history of an issue's state.\n33. As an auditor, I want label applications, assignments, and block edges\n    recorded as events, so that removals are visible even though the\n    current-state row is gone.\n34. As an auditor, I want a deleted entity's final state captured in its\n    deletion event, so that a hard delete still leaves a complete record of what\n    was lost.\n35. As an auditor, I want a created entity's initial state captured in its\n    creation event, so that history can be replayed forward from a\n    self-contained starting point.\n36. As an auditor, I want to reconstruct an entity's state at any past point, so\n    that I can answer \"what did this look like last week?\".\n37. As a host-val developer, I want the tracker to keep using prefixed table\n    names in my scoped database, so that it never collides with my own tables.\n38. As a host-val developer, I want a friendly sequential issue number, so that\n    I can refer to issues as `#N` without an extra opaque id.\n39. As an existing deployment owner, I want my current issues migrated onto the\n    new schema, so that I lose no data when upgrading.\n40. As an existing deployment owner, I want any `in_progress` issue moved to\n    `open` during migration, so that no issue is stranded in a removed state.\n41. As an existing deployment owner, I want my current JSON labels lifted into\n    the new label and join tables, so that existing tags survive the change.\n42. As an existing deployment owner, I want existing rows to get a synthetic\n    creation event on migration, so that no entity is left with no provenance.\n43. As an agent, I want the JSON API to reflect the new schema (no priority, two\n    statuses, `state_reason`, label/assignee/block operations), so that\n    non-interactive callers drive the new model correctly.\n44. As an agent, I want the API convention doc updated to the new schema, so\n    that I'm not working from the outdated contract.\n45. As a maintainer, I want any change to an issue's labels, assignees, blocks,\n    or comments to bump the issue's `updated_at`, so that \"last activity\"\n    sorting reflects all activity, not just edits to the issue's own fields.\n\n## Implementation Decisions\n\n**Modules.** The single seam of change is the data-access layer (`db.ts`):\ntypes, schema creation/migration, and all query functions. The Hono JSON API and\nthe HTML UI are consumers that will be updated to match — both currently\nduplicate schema knowledge (status/priority constants, label parse/serialize)\nthat must be reconciled to the new model. The library's public entry point and\ntable-prefixing convention are unchanged.\n\n**Removed fields.** Priority is removed entirely (column, type, filters,\ncreate/update paths) — faithful to GitHub, which has no first-class priority.\nThe `in_progress` status is removed.\n\n**Status + state_reason.** `status` is `open` | `closed`. A nullable\n`state_reason` holds `completed` / `not_planned` / `duplicate` (with `closed`)\nor `reopened` (with `open`), or `null`. It is auto-managed: create → `null`;\nclose → chosen reason (`completed` default); reopen → `reopened`. A `CHECK`\nconstraint enforces the valid pairings so an incoherent row is impossible. (ADR\ncontext: mirrors GitHub; \"not planned\" is not a third state.)\n\n**Body.** The issue's `description` is renamed to `body` so Issue and Comment\nshare one term, matching GitHub. Bodies remain `TEXT`; markdown is a rendering\ncontract, not a storage change.\n\n**Labels (ADR 0001).** A **Label** is a curated entity: `id`, unique `name`,\n`color`. Applied via an issue↔label join (bare tuple), cascade-deleting both\nsides; deleting an in-use label is allowed and simply removes the join rows. A\ndefault set (`bug`, `enhancement`, `documentation`, `question`, `duplicate`) is\nseeded **exactly once, at the moment the labels table is first created**, never\nre-seeded — so user deletions survive. Labels are editable (rename/recolour in\none place).\n\n**Assignees.** Multi-valued set of Val Town users, stored as a bare\nissue↔user-handle join tuple. No local users table; identity is the handle.\nSupports \"assigned to me\" queries in both directions.\n\n**Blocking (ADR 0002).** A directed edge `blocker → blocked`, stored once with a\nunique pair constraint and cascade on issue delete. \"Blocks\" and \"blocked by\"\nare the same edge read from opposite ends. The graph is a **strict DAG**: on\ninsert, reject if the target can already reach the source (reachability check\nvia recursive query), which covers self-edges, direct reciprocals, and longer\ncycles alike — deliberately stricter than GitHub. \"Blocked\" is **derived, never\nstored**: an issue is blocked iff any blocker is still `open`; blocked-ness is\ninformational and does not prevent closing.\n\n**Audit + provenance (ADR 0003 as amended, ADR 0004).** Entities (Issue,\nComment, Label) keep only `created_at` + `updated_at` columns (for hot-path\nlisting / \"last activity\" sorting). There are **no `*_by` columns anywhere**;\nactor/provenance lives solely in the events log. Link rows carry no audit\ncolumns. Every entity is editable, including comments (the old comment `author`\ncolumn is gone; the author is derived from the `comment.created` event).\n\n**Events log (ADR 0004).** One append-only, polymorphic table with roughly this\nshape:\n\n| column            | meaning                                                                                 |\n| ----------------- | --------------------------------------------------------------------------------------- |\n| `id`              | ordering key                                                                            |\n| `event_type`      | `<entity>.<verb>`, entity ∈ {issue, comment, label}, verb ∈ {created, updated, deleted} |\n| `entity_id`       | id of the affected entity                                                               |\n| `actor`           | Val Town handle that performed the change                                               |\n| `data`            | JSON payload (shape depends on verb)                                                    |\n| `event_timestamp` | when it happened                                                                        |\n\nGrammar — _boundary events snapshot, updates carry deltas_:\n\n- `*.created` → full initial-state snapshot.\n- `*.deleted` → full final-state snapshot (entities are hard-deleted; the event\n  is the tombstone — soft-delete was considered and rejected).\n- `*.updated` → `{ update_target, from, to }`.\n- Associations (label apply/remove, assign/unassign, block add/remove) are\n  modelled as `issue.updated` events with `update_target` ∈ {`label`,\n  `assignee`, `blocks`, `blocked_by`} and `from`/`to` using **`null ↔ value`**\n  (null→X = added, X→null = removed). No separate verb or link entity type.\n- One event per changed field: closing emits two events (`status` and\n  `state_reason`) sharing one actor and timestamp; a \"closed as not planned\"\n  timeline line is a read-time grouping by (actor, timestamp).\n- A block edge writes **one** event, on the acting issue; the reverse \"blocked\n  by\" view is derived by querying events whose `to` references the issue.\n\n**Identity / numbering.** Issues keep the autoincrement `id` as their friendly\n`#N` — no separate opaque id, since a single scoped database per host makes `id`\na clean per-tracker counter and there are no PRs competing for the sequence.\n\n**Touch rule.** Mutating an issue's labels, assignees, block edges, or comments\nbumps that issue's `updated_at` (in addition to emitting an event).\n\n**Migration.** This is a breaking change against ~3 existing deployments (this\nval + two test vals). Migration must: rename `description` → `body`; drop\n`priority`; remap any `in_progress` issue to `open`; lift each existing JSON\n`labels` array into the new label entities (creating labels as needed) and\nissue↔label join rows; move any existing single `assignee` into the assignee\njoin; and backfill a synthetic `*.created` event (and any needed state) for\nexisting rows so nothing is left provenance-less. Migration runs within the\nexisting idempotent schema-init path and must be safe to run repeatedly.\n\n**API + docs.** The JSON API is updated to the new model: no `priority`, two\nstatuses, `state_reason` on close/reopen, and label / assignee / block\noperations. The convention doc `docs/issue-tracker-valtown.md` is rewritten to\nthe new schema (it currently documents the old one) as part of this work.\n\n## Testing Decisions\n\n**Seam.** A single new seam: the exported functions of the data-access layer\n(`db.ts`). There is no existing test suite, so this is the first — no prior art\nto mirror; establish the pattern here. Tests run against a scoped SQLite\ndatabase and exercise the exported functions directly, with no HTTP or UI in the\nloop.\n\n**What makes a good test here.** Assert _external behaviour_ of the data layer —\nthe observable outcomes of calling its functions — not internal implementation\n(not specific SQL, indexes, or private helpers). A good test states a domain\nrule and checks it holds.\n\n**Behaviours to cover:**\n\n- Status/reason: create leaves reason null; each close reason sets status closed\n  with the right reason; reopen sets `reopened`; the `CHECK` constraint rejects\n  an incoherent pair.\n- Labels: default set seeded on first creation; deletions survive a re-init\n  (seed-once); applying/removing labels; deleting an in-use label removes its\n  join rows.\n- Assignees: add/remove; \"assigned to me\" returns the right issues.\n- Blocking: self-edge rejected; direct reciprocal rejected; longer cycle\n  rejected; a valid edge accepted; \"blocked\" derived from open blockers; closing\n  a blocker unblocks dependents; a blocked issue can still be closed.\n- Events: create/update/delete emit events with correct type, actor, and payload\n  grammar (created/deleted snapshots, update deltas, association `null ↔ value`,\n  one-event-per- field on close, single event on block add); deleted-entity\n  snapshot is complete.\n- Touch: association and comment changes bump the parent issue's `updated_at`.\n- Migration: from a seeded old-schema database, `in_progress` → `open`, JSON\n  labels lifted into tables, `description` readable as `body`, and existing rows\n  gain creation events; running migration twice is a no-op.\n\n## Out of Scope\n\n- Rendering markdown to HTML, and rendering the events log as a UI activity\n  timeline (data supports both; presentation is deferred — see\n  `docs/backlog.md`).\n- Turning user handles into clickable profile links (backlog).\n- Reintroducing priority or an `in_progress` state in any form.\n- A local users table or any identity beyond the Val Town handle.\n- Soft delete / restore (explicitly rejected in favour of hard delete +\n  tombstone event).\n- Retention or pruning of the append-only events log.\n- Topological \"what should I work on next\" ordering (the strict DAG keeps the\n  door open for it later, but it is not built here).\n- Black-box tests at the HTTP/API layer (single `db.ts` seam only, by decision).\n\n## Further Notes\n\n- Governing decisions live in ADRs 0001–0004 and the glossary in `CONTEXT.md`;\n  use that vocabulary in issue titles, tests, and code.\n- Deferred wants are tracked in `docs/backlog.md`.\n- The stale `docs/issue-tracker-valtown.md` is intentionally left untouched\n  until this work rewrites it, so nothing points agents at the new schema before\n  it exists.\n",[],[322,541,542,552],"09a12ef3-b79f-45bc-b0d7-6c7e712da8e8","ee584d8c-7bf2-11f1-8d5b-1607ee4eb77e",138,["D",1783641873720],[367,368,369],[322,541,542],"d15000a3-b025-47ce-89ad-8e9ceb3f49dd","b3ab7362-7fb7-11f1-8f98-1607ee4eb77e","b3107e7a-7fb7-11f1-b594-1607ee4eb77e",310,["D",1784074131135],"# PRD: GitHub-style UI refactor\n\nStatus: resolved\n\nWireframes for every screen live in `wireframes/` (browsable viewer at\n`wireframes/index.html`). They are the visual reference for this spec; the red\ndashed marks in them are annotations, not UI.\n\n## Problem Statement\n\nThe tracker's current UI is a functional but ad-hoc set of server-rendered\npages: the issue list is a dense table with no labels visible, filtering is a\nrow of separate form fields, issue management is a long single column of\nalways-visible forms stacked under the body, and label management looks nothing\nlike the rest of the app. For a user who lives in GitHub Issues, none of it\nmatches the mental model they already have, and the triage signal (labels like\n`ready-for-agent`) is invisible exactly where triage happens: the list.\n\n## Solution\n\nRestyle all pages after the GitHub Issues interface while keeping the existing\nroutes, role model, storage, and API untouched. A slim shared top bar (Issues ·\nLabels · current user) replaces per-page navigation. The issue list becomes a\ntoken search bar plus a panel of stacked rows with Open/Closed tabs, label\nchips, and a Blocked pill. The issue detail page becomes a two-column layout:\nthe body as the first comment card and the thread on the left, management\n(assignees, labels, relationships, delete) in a right sidebar of gear-revealed\nsections, with close-with-reason in the composer footer. Label management gains\na search input and an inline expanding create row. Issue creation gets a focused\ntitle + description column with metadata pickers in a sidebar. Everything stays\nserver-rendered and works without client-side JavaScript, using progressive\ndisclosure (`<details>`) and plain form posts.\n\n## User Stories\n\n1. As a user on any page, I want a consistent top bar with Issues and Labels\n   tabs and my handle/avatar, so that I always know where I am and can move\n   between the two surfaces in one click.\n2. As a visitor in standalone mode, I want the top bar to show a log in link\n   when I am signed out (and log out when signed in), so that the existing auth\n   affordances survive the redesign.\n3. As a user browsing issues, I want Open and Closed tabs with count pills at\n   the top of the list panel, so that I can switch lifecycle views and see\n   volumes at a glance.\n4. As a user browsing issues, I want each issue as a stacked row (state icon,\n   bold title, meta line, label chips), so that I can scan titles and triage\n   labels without opening anything.\n5. As a triager, I want label chips visible under each issue title in the list,\n   so that I can spot `ready-for-agent` vs `ready-for-human` work without\n   opening each issue.\n6. As a user browsing issues, I want a Blocked pill in a row's meta line when at\n   least one blocker is still open, so that I can skip work that cannot proceed.\n7. As a user browsing issues, I want each row's meta line to show number,\n   author, opened time, and last-updated time, so that I can judge freshness the\n   same way I do on GitHub.\n8. As a user browsing issues, I want rows sorted by last activity, so that the\n   most recently touched issues surface first.\n9. As a user browsing issues, I want a comment count on rows that have comments,\n   so that I can see where discussion is happening.\n10. As a user filtering issues, I want a single search bar that accepts\n    `status:` and `assignee:` tokens plus free text, so that one input replaces\n    the old row of separate filter fields.\n11. As a user filtering issues, I want free text in the search bar matched\n    against issue titles and bodies, so that I can find issues by content.\n12. As a contributor, I want a New issue button next to the search bar, so that\n    creating an issue is one click from the list.\n13. As a viewer (read-only role), I want the New issue button hidden, so that\n    the UI never offers actions I cannot perform.\n14. As a contributor creating an issue, I want a focused page with a required\n    title field and a description editor, so that writing is the primary\n    activity.\n15. As a contributor creating an issue, I want assignees and labels in a sidebar\n    with disclosure pickers over the curated label set, so that metadata never\n    interrupts the writing flow.\n16. As a contributor creating an issue, I want an \"assign yourself\" shortcut in\n    the Assignees section, so that self-assignment is one click.\n17. As a contributor creating an issue, I want a Create more checkbox that\n    returns me to a fresh form after submitting, so that I can enter several\n    issues in a row.\n18. As a contributor creating an issue, I want submitting without a title to\n    re-render the form with an error and my input preserved, so that I do not\n    lose work.\n19. As a user reading an issue, I want the title with the issue number, a filled\n    Open (or Closed) pill, and a Blocked pill when applicable, so that state is\n    legible at the top.\n20. As a user reading an issue, I want the body rendered as the first comment\n    card with author, opened time, an edited marker, and a role badge, so that\n    provenance reads like GitHub.\n21. As a user reading an issue, I want comments as cards with author and time,\n    so that the thread is easy to follow.\n22. As a user reading a closed issue, I want the close reason visible\n    (completed, not planned, duplicate), so that I know why it was closed.\n23. As a user reading a reopened issue, I want the reopened state visible, so\n    that I can distinguish it from a never-closed issue.\n24. As a commenter, I want a composer at the end of the thread with a Comment\n    button, so that replying is immediate.\n25. As a viewer, I want the composer replaced by a read-only notice, so that the\n    page degrades honestly for my role.\n26. As an issue manager (creator or maintainer), I want Close issue with a\n    reason chooser in the composer footer, so that closing with the right state\n    reason is part of the natural flow.\n27. As an issue manager, I want Reopen offered in the same spot when the issue\n    is closed, so that the lifecycle actions live in one place.\n28. As an issue manager, I want a sidebar with Assignees, Labels, and\n    Relationships sections that stay quiet until I open their controls, so that\n    reading is undisturbed by forms.\n29. As an issue manager, I want each sidebar section's controls revealed by a\n    disclosure (gear), so that add/remove actions are available without\n    permanent clutter.\n30. As an issue manager, I want to add and remove labels via a picker over the\n    curated set, so that labeling is choosing, never typing.\n31. As an issue manager, I want to add and remove assignees by Val Town handle,\n    so that responsibility stays visible.\n32. As an issue manager, I want the Relationships section to show both\n    directions (blocked by / blocks) with each blocker's open/closed state, so\n    that I understand the dependency picture.\n33. As an issue manager, I want adding a blocking edge that would create a cycle\n    to fail with a clear error, so that the DAG guarantee is surfaced, not\n    silent.\n34. As a comment author (or maintainer), I want edit and delete on my comments\n    via each card's overflow, so that moderation matches GitHub.\n35. As a maintainer, I want Delete issue in the sidebar clearly separated and\n    marked maintainer-only, so that the destructive action is hard to hit by\n    accident.\n36. As a user with no manage rights, I want the sidebar management controls\n    absent entirely, so that role boundaries render as absences, not errors.\n37. As an issue manager, I want a pencil next to the title leading to the edit\n    page, so that fixing a title or body is one click.\n38. As a user of the labels page, I want a search input over labels, so that I\n    can find a label as the set grows.\n39. As a user of the labels page, I want rows showing chip, hex color, and\n    open-issue count, so that I can see each label's look and usage.\n40. As a maintainer, I want New label to expand an inline create row (preview\n    chip, name, color with swatch), so that creation happens in place rather\n    than on another page.\n41. As a maintainer, I want edit and delete behind each label row's overflow\n    menu, so that management is available but not shouting.\n42. As a maintainer, I want the open-issue count visible before deleting a\n    label, so that the cascade (label vanishing from issues) is a visible\n    consequence.\n43. As a host-val owner mounting the tracker in routed mode, I want the compact\n    top bar to be the only chrome, so that the tracker embeds politely under my\n    router's own UI.\n44. As a keyboard or assistive-tech user, I want all interactions to be links,\n    forms, and native disclosures, so that the UI works without JavaScript and\n    with standard semantics.\n45. As a future user, I want a Preview tab slot in the editors that activates\n    when markdown rendering lands, so that the layout will not shift when the\n    roadmap catches up.\n46. As a triager, I want a `label:` search token (and a Labels dropdown that\n    injects it), so that I can narrow the list to a specific triage label like\n    `ready-for-agent`. Token values containing spaces use percent encoding, so\n    the label `good first issue` is written as `label:good%20first%20issue`;\n    unencoded `label:good first issue` is not a multi-word label token.\n47. As a user filtering issues, I want an `author:` search token (and an Author\n    dropdown), so that I can see issues opened by a given handle.\n48. As a user filtering issues, I want `is:blocked` / `is:unblocked` tokens (and\n    a Blocked/Unblocked dropdown), so that I can focus on work that can or\n    cannot proceed.\n49. As a user filtering issues, I want the Open/Closed tabs and every dropdown\n    to edit tokens in the one search query rather than replace it, so that\n    filters compose instead of clobbering each other.\n\n## Implementation Decisions\n\n- **Preserve public behavior contracts.** Routes, JSON API shapes, the `Issue`\n  model, database schema, and role model (viewer / contributor / maintainer,\n  standalone vs routed, the auth-UI signal) stay unchanged. Minimal internal\n  store projections and aggregate-write methods may support bounded rendering\n  and atomic creation without changing those public contracts.\n- **Shared top bar in the layout component.** 64px bar rendered on every page:\n  Issues and Labels tabs with an active underline, current user handle and\n  avatar on the right, and the existing login/logout affordance when the auth UI\n  is enabled. All page-local back links and duplicate New issue buttons are\n  removed in favor of the bar.\n- **Zero-JS-first, progressive disclosure.** Every interaction must work as\n  plain links and form posts. Gear-revealed sidebar sections, the inline label\n  create row, overflow menus, and pickers are `<details>`/`<summary>`\n  disclosures. No client-side framework; if a sprinkle of JS is ever added it\n  must be an enhancement, not a requirement.\n- **Token search, parsed server-side.** The list's single search input submits\n  one query parameter. The server parses `status:<open|closed>`,\n  `assignee:<handle>`, `label:<name>`, `author:<handle>`, and\n  `is:blocked`/`is:unblocked` tokens out of it, in any order. `status` and\n  `assignee` feed the list projection; `label`, `author`, and blocked-ness are\n  applied in-route (`blocked` stays a derived property). Token values are\n  percent-encoded when they contain whitespace: `label:good%20first%20issue` is\n  valid, while `label:good first issue` parses as the simple `label:good` token\n  plus free text. The remainder, and any unrecognized token, become the\n  free-text search. Old `status`/`assignee`/`search` query parameters keep\n  working.\n- **Token-injecting filter dropdowns.** The list header carries Author, Labels,\n  and Blocked/Unblocked dropdowns built as `<details>` disclosures; choosing an\n  entry adds or replaces the matching token (`author:`, `label:`,\n  `is:blocked`/`is:unblocked`) in the query and submits. They are conveniences\n  over the search bar, which stays the single source of truth; zero-JS via\n  native disclosures and form posts.\n- **Open/Closed tabs replace the metric tiles and the status dropdown.** Counts\n  render as pills on the tabs. The tabs are links that rewrite the `status:`\n  token in the current query, preserving every other token; the active tab\n  reflects the effective status filter (default: open).\n- **Stacked list rows replace the table.** Row anatomy: state icon, bold title\n  (linking to the detail page), optional Blocked pill, meta line (number,\n  author, opened relative time, updated relative time), label chips, and a\n  right-aligned comment count when nonzero. Blocked remains a derived property\n  (an open blocker exists), never stored.\n- **Detail page is two-column.** Main column: the issue body as the first\n  comment card (author, opened time, edited marker, a role badge when the author\n  is a maintainer), then comment cards, then the composer. Sidebar: Assignees,\n  Labels, Relationships, and Delete sections separated by hairlines, each\n  section's mutation controls inside a disclosure and rendered only for users\n  allowed to use them (manage rights for issue associations; maintainer for\n  delete). Relationships lists both edge directions with each related issue's\n  status; the existing cycle-rejection error surfaces through the existing error\n  banner.\n- **Lifecycle actions live in the composer footer.** Close issue with a reason\n  chooser (completed default, not planned, duplicate) next to the Comment\n  button; Reopen replaces it when the issue is closed. These call the existing\n  close/reopen routes.\n- **Create/edit pages.** Create: required title, description textarea in a\n  Write-tab editor frame with a visible but inert Preview slot (activates when\n  markdown rendering ships), sidebar sections for assignees (including\n  assign-yourself) and label picking, footer with Create, Cancel, and a Create\n  more checkbox that redirects back to the create form instead of the new issue.\n  Edit mirrors create with title + body only. Assignee handles remain\n  unvalidated; the form notes this.\n- **Labels page.** Heading with maintainer-only New label button that expands an\n  inline create row (live-preview chip, name, color with swatch) posting to the\n  existing create-label route; a search input filtering labels by name\n  (server-side, query parameter); rows of chip, hex color, open-issue count, and\n  an overflow disclosure containing edit-in-place and delete. Label deletion\n  behavior is unchanged (cascade off issues; defaults seeded once per ADR 0001 —\n  the page never re-seeds).\n- **Open-issue count per label** is computed with a join at render time; no\n  schema change.\n- **Monochrome-agnostic styling.** The wireframes are lo-fi; the implementation\n  keeps the app's existing styling approach and dark palette, mapping wireframe\n  structure (not colors) onto it. Label chips continue to use each label's\n  stored color.\n\n## Testing Decisions\n\n- **Single seam: the HTTP handler.** All tests drive the app through the tracker\n  factory called with an in-memory store, exactly as the existing form-driven\n  test does: build a request, call the returned handler, assert on status,\n  redirect location, and markers in the rendered HTML.\n- **Good tests assert external behavior, not markup internals.** Assert that the\n  open/closed counts render, that a blocked issue's list row contains the\n  Blocked marker, that a viewer's page omits the New issue and composer\n  affordances, that token search narrows results, that Create more redirects\n  back to the form — not that a specific class name or element nesting is\n  present. String markers should be user-visible text or stable landmarks.\n- **Prior art:** the existing end-to-end form test (`app_test` — HTML forms\n  drive create, lifecycle, labels, assignees, blocks, and comments) is the\n  model: in-memory SQLite via the test store factory, `auth: false`, form posts,\n  HTML assertions. New tests extend this file's style; role-gating tests can\n  construct routed contexts the same way existing routed tests do.\n- **The JSON API tests are untouched** — the API surface does not change.\n\n## Out of Scope\n\n- **Markdown rendering** and therefore Preview activation; the Preview tab ships\n  visibly inert (roadmap).\n- **Personal views** (assigned to me, created by me, recent activity) — deferred\n  until there is real multi-user traffic.\n- **Sort menus** and any other header dropdowns beyond Author, Labels, and\n  Blocked/Unblocked (which now ship — see Implementation Decisions); sort stays\n  fixed at last activity.\n- **Label descriptions** — explicitly decided against; no schema change.\n- **Mobile-specific layouts** — the pages remain simple enough to degrade, but\n  no dedicated responsive pass in this effort.\n- **Pagination**, file attachments, notifications, milestones, projects, and any\n  other GitHub feature without an existing backend.\n- **API or schema changes of any kind.**\n\n## Further Notes\n\n- Final recertification on 2026-07-14 verified all seven child tickets as\n  resolved with no unchecked acceptance criteria. Focused regressions for the\n  issue-body edited marker and the one-query label-summary projection passed,\n  followed by `deno fmt --check`, `deno task lint`, `deno task typecheck`, and\n  `deno task test` (43 passed, 0 failed).\n- Visual reference: `wireframes/issue-list.svg`, `wireframes/issue-detail.svg`,\n  `wireframes/issue-new.svg`, `wireframes/labels.svg`, flow overview in\n  `wireframes/flow.svg`, all browsable via `wireframes/index.html`.\n- The wireframes were iterated against GitHub Issues screenshots supplied during\n  the design session; decisions recorded there and folded in here: top bar over\n  sidebar nav, no label descriptions, personal views deferred, Preview marked\n  roadmap.\n- Relative-time formatting (\"3d ago\") appears throughout the wireframes; the\n  current UI shows absolute dates. Treat relative times as the target, but this\n  is a presentation detail, not a contract.\n- If disclosure-based pickers prove awkward for multi-select labeling in\n  practice, the fallback is the current always-visible form for that one\n  section; keep the section anatomy either way.\n",[],[322,541,573,552],"github-style-ui","e8e734c2-605d-4072-96d6-888c0c2e38a5","07-labels-page.md","b3803c74-7fb7-11f1-bc45-1607ee4eb77e","b3318a70-7fb7-11f1-bc45-1607ee4eb77e",312,["D",1784074131216],"# 07 — Labels page\n\n**What to build:** The labels page becomes GitHub-like. A search input filters\nlabels by name server-side via a query parameter. Each label renders as a row\nshowing its chip, hex color, and open-issue count (computed with a join at\nrender time — no schema change). A maintainer-only New label button expands an\ninline create row with a live-preview chip, a name field, and a color field with\na swatch, posting to the existing create-label route. Each row has an overflow\ndisclosure containing edit-in-place and delete; the visible open-issue count\nmakes the delete cascade (the label vanishing from that many issues) a visible\nconsequence. Label deletion behavior is unchanged.\n\n**Blocked by:** 01\n\n**Status:** resolved\n\n- [x] A search input filters the label list by name (server-side)\n- [x] Each row shows the label chip, its hex color, and its open-issue count\n- [x] Open-issue counts are computed with a render-time join rather than by\n      loading and aggregating every issue in application memory\n- [x] A maintainer sees New label, which expands an inline create row with a\n      live-preview chip, name, and color-with-swatch, and creating a label works\n      via the existing route\n- [x] Edit-in-place and delete live behind each row's overflow disclosure\n- [x] A non-maintainer sees the list and counts but no create/edit/delete\n      controls\n- [x] No route, API, or schema change; the store gains only an internal read\n      projection (permitted by the PRD, which requires the join)\n\n## Comments\n\n- Rebuilt the labels surface with server-side name search, label chips, hex\n  colors, open-issue counts, and maintainer-only native disclosures for create,\n  edit, and delete actions.\n- Added a progressive-enhancement preview for new label name/color changes;\n  creation still works as a normal form post without JavaScript.\n- Validation passed: `deno task check` (format, lint, typecheck, and 32 tests).\n- Independent recertification reopened this ticket: the rendered counts are\n  correct, but the route still aggregates `store.listIssues()` in memory rather\n  than using the PRD-required render-time join.\n- Closed the reopened box with a `store.listLabelSummaries({ search })`\n  projection: one `LEFT JOIN` over labels → issue_labels → issues counting\n  `status = 'open'`, with name search pushed into the same query. The route no\n  longer loads every issue to render the labels page. This is the \"minimal\n  internal store projection\" the PRD allows (same shape as the existing\n  `listIssueRows` / `listIssueAuthors`); routes, API, and schema are unchanged.\n- Label search now escapes `%` and `_`, so searching for a literal `%` matches\n  nothing instead of every label.\n- Validation: `deno task check` (format, lint, typecheck, 43 tests). New db test\n  pins the counts, the closed-issue exclusion, and a one-query bound; the\n  existing labels-page route test covers the rendering end to end unchanged.\n- Reworded the last acceptance box: it claimed \"no store change\" while the box\n  above it mandates a render-time join, which only SQL in the store can do. The\n  two are consistent only if that box means the _public_ contracts (routes, JSON\n  API, schema), which is what the PRD protects and what this change preserves.\n- Review follow-ups applied: extracted a `toLabel` row mapper (the summary query\n  was becoming a fifth copy) and named the search helper `containsPattern`.\n- Known, accepted: SQLite's `LIKE` folds case for ASCII only, where the previous\n  JS `.toLowerCase()` folded all of Unicode. `?q=BUG` still finds `bug`; a label\n  named `étiquette` would no longer match `?q=ÉTIQUETTE`. No such label exists\n  and the curated set is ASCII, so this is not worth an ICU dependency.\n- Left alone deliberately: issue free-text search (`db.ts` `listIssues`) still\n  passes `%` through as a wildcard. That is ticket 02's token-search contract\n  with its own tests; changing it here would be scope creep.\n",[],[322,541,573,541,575],"f2dd4743-552c-4e6a-9fb4-750845d83536","06-create-and-edit-pages.md","b3c28c8c-7fb7-11f1-b19c-1607ee4eb77e",297,["D",1784073502367],"# 06 — Create & edit pages\n\n**What to build:** The create page becomes a focused writing column: a required\ntitle field and a description textarea inside a Write-tab editor frame with a\nvisible but inert Preview tab slot (activates when markdown rendering ships). A\nsidebar holds an Assignees section with an assign-yourself shortcut and a Labels\npicker over the curated set. The footer has Create, Cancel, and a Create more\ncheckbox that returns to a fresh create form after submitting instead of the new\nissue. Submitting without a title re-renders the form with an error and\npreserves the entered input. The edit page mirrors this layout with title and\nbody only. Assignee handles remain unvalidated, and the form notes this.\n\n**Blocked by:** 01\n\n**Status:** resolved\n\n- [x] Create shows a required title, a description editor with a Write tab and\n      an inert Preview slot, and a sidebar with Assignees (incl.\n      assign-yourself) and a label picker\n- [x] Submitting with a title creates the issue with the chosen labels and\n      assignees\n- [x] Submitting without a title re-renders the form with an error and the\n      previously entered body/metadata preserved\n- [x] The Create more checkbox redirects back to a fresh create form instead of\n      the new issue\n- [x] Edit mirrors the layout with title + body and saves via the existing route\n- [x] Existing routes, JSON API, `Issue`, and schema behavior are unchanged;\n      creation uses a minimal aggregate store operation so issue plus selected\n      metadata commits atomically\n\n## Comments\n\n- Rebuilt the create page as a focused title/body editor with native Write and\n  inert Preview tabs, a disclosure-based assignee/label sidebar, assign-yourself\n  and create-more controls, and preserved invalid form state.\n- Reworked edit to share the editor frame while keeping metadata on the issue\n  page. Existing routes and storage interfaces remain unchanged.\n- Added HTTP-level coverage for create/edit rendering, validation round-trips,\n  label and assignee application, assign-yourself, create-more redirects, and\n  successful editing.\n- Validation passed: `deno task check` (format, lint, typecheck, and 31 tests).\n- Standards repair: create now rolls back the issue, metadata links, and events\n  if a selected label is stale or any later aggregate write fails. Event\n  ordering, actor provenance, and last-activity semantics are preserved.\n",[],[322,541,573,541,584],"a57fcd9d-6854-4cfe-aaf8-d2a1f4dd3cd5","05-issue-detail-management-sidebar.md","b3cc82c8-7fb7-11f1-99dd-1607ee4eb77e",283,["D",1784068737922],"# 05 — Issue detail: gear-revealed management sidebar\n\n**What to build:** The detail page's right column gains a management sidebar\nwith Assignees, Labels, and Relationships sections separated by hairlines, each\nsection's add/remove controls tucked inside a gear `<details>` disclosure so\nreading stays undisturbed. Labels are added/removed via a picker over the\ncurated set; assignees added/removed by Val Town handle; Relationships lists\nboth directions (blocked by / blocks) with each related issue's open/closed\nstate, and an edge that would create a cycle fails through the existing error\nbanner. Each comment card gains an overflow disclosure with edit and delete for\nits author (or a maintainer). A maintainer-only Delete issue sits clearly\nseparated at the bottom. For users without manage rights the sidebar controls\nare absent entirely, and delete is absent for non-maintainers.\n\n**Blocked by:** 04\n\n**Status:** resolved\n\n- [x] Managers see Assignees, Labels, and Relationships sections whose controls\n      are revealed by a disclosure\n- [x] Labels can be added/removed via a picker over the curated set; assignees\n      added/removed by handle\n- [x] Relationships shows both blocked-by and blocks with each related issue's\n      state; a cycle-creating edge surfaces the existing error via the banner\n- [x] A comment's author or a maintainer can edit and delete it from the card's\n      overflow\n- [x] Delete issue appears only for maintainers and is visually separated;\n      non-managers see no sidebar controls at all (no errors)\n- [x] No route, store, API, or schema change\n\n## Comments\n\n- Wrapped the existing assignee, label, and relationship mutation forms in\n  native gear disclosures while keeping current state visible in the sidebar.\n- Added overflow actions to comment cards and preserved the existing author /\n  maintainer authorization and mutation routes.\n- Added HTTP-level coverage for manager/viewer gating, both relationship\n  directions, add/remove mutations, comment actions, maintainer-only deletion,\n  and cycle rejection.\n- Validation passed: `deno task check` (format, lint, typecheck, and 30 tests).\n",[],[322,541,573,541,592],"ce4129c7-8914-422c-8d2a-fff3acf94330","04-issue-detail-reading-shell.md","b38c5cca-7fb7-11f1-9940-1607ee4eb77e",295,["D",1784073502182],"# 04 — Issue detail: reading shell + lifecycle composer footer\n\n**What to build:** The issue detail page becomes a two-column reading surface.\nThe header shows the title with its number, a filled Open (or Closed) pill, a\nBlocked pill when an open blocker exists, and a pencil linking to the edit page.\nThe body renders as the first comment card — author, opened relative time, an\nedited marker when edited, and a role badge when the author is a maintainer —\nfollowed by the comment thread as cards (each with author and time; a closed\nissue shows its close reason, a reopened issue shows the reopened state). The\nthread ends in a composer whose footer carries the lifecycle action: Close issue\nwith a reason chooser (completed default, not planned, duplicate) for an open\nissue, or Reopen for a closed one, beside the Comment button. Viewers get a\nread-only notice instead of the composer.\n\n**Blocked by:** 01\n\n**Status:** resolved\n\n- [x] The header shows title + number, a filled Open/Closed pill, a Blocked pill\n      when applicable, and an edit pencil\n- [x] The body appears as the first comment card with author, opened time, an\n      edited marker when edited, and a maintainer badge when applicable\n- [x] Comments render as cards; a closed issue shows its close reason and a\n      reopened issue shows the reopened state\n- [x] A manager sees Close-with-reason (open) or Reopen (closed) in the composer\n      footer, and closing/reopening still works via the existing routes\n- [x] A viewer sees a read-only notice and no composer\n- [x] No route, store, API, or schema change\n\n## Comments\n\n- Implemented the two-column issue reading shell with a title/state header, edit\n  pencil, blocked marker, first-post body card, comment cards, and a\n  zero-JavaScript composer with an inert Preview slot.\n- Lifecycle controls now live beside Comment in the composer footer; the\n  existing close/reopen routes remain unchanged, and the existing event log\n  supplies the content-edited marker.\n- Added HTTP-level coverage for manager/viewer rendering, blocked state,\n  maintainer badge, close reasons, reopen state, and read-only gating.\n- Validation passed: `deno task check` (format, lint, typecheck, and 29 tests).\n- Independent recertification reopened this ticket: the body card currently\n  shows `edited` after a title-only edit even when the body was unchanged.\n- Fixed: the `bodyEdited` derivation in `app.tsx` matched `update_target` of\n  `title` _or_ `body`, so any title edit marked the body card. It now matches\n  `body` only. `updateIssue` emits one `issue.updated` event per field that\n  actually changed, so the `body` target is an exact signal that the body was\n  edited.\n- Added a regression test to the reading-shell test: a title-only edit leaves\n  the card unmarked, and a following body edit marks it.\n- Validation passed: `deno task check` (format, lint, typecheck, and 42 tests).\n",[],[322,541,573,541,600],"4a76833a-2670-43a5-835a-4e636480997a","03-filter-dropdowns.md","b3dadfc6-7fb7-11f1-add4-1607ee4eb77e",298,["D",1784073502306],"# 03 — Token-injecting filter dropdowns\n\n**What to build:** The list header gains three dropdowns — Author, Labels, and\nBlocked/Unblocked — each a native `<details>` disclosure listing its choices\n(author handles drawn from existing issues, the curated label set, and\nblocked/unblocked). Choosing an entry adds or replaces the matching token\n(`author:`, `label:`, `is:blocked`/`is:unblocked`) in the current query and\nsubmits, so the search bar stays the single source of truth. Everything works\nwith no client JavaScript. Dropdown emission and route parsing share the same\npercent-encoded token grammar, including multi-word label names.\n\n**Blocked by:** 02\n\n**Status:** resolved\n\n- [x] The list header shows Author, Labels, and Blocked/Unblocked disclosures\n- [x] Choosing a label adds `label:<name>` to the query and filters the list\n      accordingly\n- [x] Choosing an author adds `author:<handle>`; choosing Blocked/Unblocked adds\n      `is:blocked`/`is:unblocked`\n- [x] Selecting a value when its token already exists replaces it rather than\n      duplicating it\n- [x] The dropdowns operate without JavaScript (native disclosure + form post)\n- [x] No route, JSON API, or schema change\n\n## Comments\n\n- Implemented native Author, Labels, and Blocked / Unblocked disclosures in the\n  issue-list header. Choices submit the current query with the selected token\n  added or replaced, and author options are derived from existing issues.\n- Added HTTP-level coverage for rendering, token injection/replacement, and\n  label filtering.\n- Validation passed: `deno task lint`, `deno task typecheck`, and the full\n  `deno task test` suite (28 tests).\n- Standards repair: multi-word labels now round-trip through percent-encoded\n  hand-written queries and dropdown selection; simple tokens such as `label:bug`\n  remain compatible. Unencoded spaces delimit tokens.\n",[],[322,541,573,541,608],"f33ae953-5b87-4be7-b025-811a5a1e0c8f","02-issue-list-search-tabs-rows.md","b3bb38ba-7fb7-11f1-9b8e-1607ee4eb77e",300,["D",1784073502522],"# 02 — Issue list: query language, Open/Closed tabs, stacked rows\n\n**What to build:** The issue list becomes a GitHub-style search-and-scan\nsurface. A single search box submits one query; the server parses `status:`,\n`assignee:`, `label:`, `author:`, and `is:blocked`/`is:unblocked` tokens in any\norder. Token values use percent encoding when needed, so multi-word label names\nremain one composable token while legacy simple tokens stay valid. Filters are\napplied over a bounded list-row projection; `blocked` stays derived. Leftover\ntext, and any unrecognized token, become the free-text search across title and\nbody. Open and Closed tabs sit above the list with count pills; clicking a tab\nrewrites only the `status:` token and preserves the rest of the query. Each\nissue renders as a stacked row: state icon, bold linked title, a Blocked pill\nwhen an open blocker exists, a meta line (number, author, opened relative time,\nupdated relative time), label chips, and a right-aligned comment count when\nnonzero. A New issue button sits by the search box for non-viewers and is hidden\nfor viewers. Old `status`/`assignee`/`search` URLs keep working.\n\n**Blocked by:** 01\n\n**Status:** resolved\n\n- [x] `status:closed` in any position (alongside other tokens) narrows to closed\n      issues; free text narrows by title/body\n- [x] `label:<name>` and `author:<handle>` narrow the list;\n      `is:blocked`/`is:unblocked` narrow by derived blocked-ness\n- [x] Open and Closed tabs show correct counts, and clicking one preserves the\n      other tokens in the query\n- [x] A blocked issue's row shows the Blocked marker; rows show number, author,\n      relative opened/updated times, label chips, and a comment count when\n      comments exist\n- [x] Viewers see no New issue button; contributors and maintainers do\n- [x] Old `?status=`/`?assignee=`/`?search=` URLs produce the same results as\n      before\n- [x] Existing routes, JSON API, `Issue`, and schema behavior are unchanged; the\n      store adds only a list-row projection used by the HTML list\n\n## Comments\n\n- Implemented server-side token parsing for the `q` query, with legacy query\n  parameters retained, route-level label/author/blocked filtering, activity\n  counts, and stacked issue rows.\n- Validation passed: `deno task check` (format, lint, typecheck, and full test\n  suite).\n- Standards repair: list rendering now uses bounded bulk association,\n  provenance, and comment-count queries instead of per-row hydration. Query\n  count and filter/order behavior have regression coverage.\n",[],[322,541,573,541,616],"d9c2f100-36ac-439b-82aa-78d0fafb7213","01-shared-top-bar.md","b3a02c82-7fb7-11f1-9b8e-1607ee4eb77e",268,["D",1784059508142],"# 01 — Shared top bar in the layout\n\n**What to build:** On every page, a slim shared top bar replaces per-page\nnavigation. It shows two tabs — Issues and Labels — with the current surface\nactive, the signed-in user's handle and avatar on the right, and the existing\nauth affordance: a log in link when signed out (wherever a login location\nexists), log out when signed in, and neither when the tracker is mounted under\nan ungated router. In routed mode the bar is the only chrome the tracker adds.\nPer-page back links and duplicate New issue / Labels buttons come out in favor\nof the bar as each page is restyled.\n\n**Blocked by:** None — can start immediately.\n\n**Status:** resolved\n\n- [x] Every page renders the top bar with Issues and Labels tabs linking to\n      their surfaces\n- [x] The tab for the current surface is visibly active\n- [x] Signed out with an available login: the bar shows a log in link; signed\n      in: it shows the user handle and a log out control\n- [x] Under an ungated routed mount, the bar shows neither log in nor log out\n- [x] Internal links respect the mount prefix in routed mode and are prefix-free\n      standalone\n- [x] No route, store, API, or schema change; existing tests still pass\n\n## Comments\n\n- Verified the shared top bar implementation in `layout.tsx`, its active-surface\n  wiring across all page components and error pages, and routed prefix/auth\n  behavior in `app.tsx` and `app_test.tsx`.\n- Validation passed: `deno task check` (format, lint, typecheck, and 26 tests).\n",[],[322,541,573,541,624],"f9ae41d9-43f3-4d72-ac25-e5ff303e87ef",238,["D",1784056238688],[358,359,360,361,362,363,364],[322,541,573,541],"2acc39c9-ac03-40d5-a465-a4e0762786f6",237,["D",1784056238504],[357,365],[322,541,573],"087701f2-85c7-4143-bf9c-c982c16aabc3",137,["D",1783641873603],[356,366],[322,541],"333d9aaa-e7b2-4eb4-b3d6-a187292833b3","triage-labels.md","ee979b04-7bf2-11f1-ab8e-1607ee4eb77e","ee3720da-7bf2-11f1-8964-1607ee4eb77e",170,["D",1783653142340],"# Triage Labels\n\nThe skills speak in terms of five canonical triage roles. This file maps those\nroles to the actual label strings used in this repo's issue tracker.\n\n| Label in mattpocock/skills | Label in our tracker | Meaning                                  |\n| -------------------------- | -------------------- | ---------------------------------------- |\n| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |\n| `needs-info`               | `needs-info`         | Waiting on reporter for more information |\n| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |\n| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |\n| `wontfix`                  | `wontfix`            | Will not be actioned                     |\n\nWhen a skill mentions a role (e.g. \"apply the AFK-ready triage label\"), use the\ncorresponding label string from this table.\n\n> Note: these five are the **skills' workflow** labels applied to `docs/issues/`\n> tickets. They are a different axis from the issue-tracker _product's_ labels\n> (`bug`, `enhancement`, `documentation`, `question`, `duplicate`) defined in\n> `CONTEXT.md`. Don't conflate the two.\n\nEdit the right-hand column to match whatever vocabulary you actually use.\n",[],[322,655,647],"agents","82f10ed3-774a-43fd-9359-15b8c0e73a99","issue-tracker.md","eea668c8-7bf2-11f1-8b8f-1607ee4eb77e",171,["D",1783653142513],"# Issue tracker: Local Markdown\n\nIssues and PRDs for this repo live as markdown files in `docs/issues/`.\n\n## Conventions\n\n- One feature per directory: `docs/issues/<feature-slug>/`\n- The PRD is `docs/issues/<feature-slug>/PRD.md`\n- Implementation issues are `docs/issues/<feature-slug>/issues/<NN>-<slug>.md`,\n  numbered from `01`\n- Triage state is recorded as a `Status:` line near the top of each issue file\n  (see `triage-labels.md` for the role strings)\n- Comments and conversation history append to the bottom of the file under a\n  `## Comments` heading\n\n## When a skill says \"publish to the issue tracker\"\n\nCreate a new file under `docs/issues/<feature-slug>/` (creating the directory if\nneeded).\n\n## When a skill says \"fetch the relevant ticket\"\n\nRead the file at the referenced path. The user will normally pass the path or\nthe issue number directly.\n\n## Wayfinding operations\n\nUsed by `/wayfinder`. The **map** is a file with one **child** file per ticket.\n\n- **Map**: `docs/issues/<effort>/map.md` — the Notes / Decisions-so-far / Fog\n  body.\n- **Child ticket**: `docs/issues/<effort>/issues/NN-<slug>.md`, numbered from\n  `01`, with the question in the body. A `Type:` line records the ticket type\n  (`research`/`prototype`/`grilling`/`task`); a `Status:` line records\n  `claimed`/`resolved`.\n- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked\n  when every file it lists is `resolved`.\n- **Frontier**: scan `docs/issues/<effort>/issues/` for files that are open,\n  unblocked, and unclaimed; first by number wins.\n- **Claim**: set `Status: claimed` and save before any work.\n- **Resolve**: append the answer under an `## Answer` heading, set\n  `Status: resolved`, then append a context pointer (gist + link) to the map's\n  Decisions-so-far in `map.md`.\n",[],[322,655,657],"761446ff-c75d-4331-83d4-ae4f43707105","domain.md","ee8a62a4-7bf2-11f1-9482-1607ee4eb77e",169,["D",1783653142230],"# Domain Docs\n\nHow the engineering skills should consume this repo's domain documentation when\nexploring the codebase.\n\n## Before exploring, read these\n\n- **`CONTEXT.md`** at the repo root, or\n- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one\n  `CONTEXT.md` per context. Read each one relevant to the topic.\n- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In\n  multi-context repos, also check `src/<context>/docs/adr/` for context-scoped\n  decisions.\n\nIf any of these files don't exist, **proceed silently**. Don't flag their\nabsence; don't suggest creating them upfront. The `/domain-modeling` skill\n(reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates\nthem lazily when terms or decisions actually get resolved.\n\n## File structure\n\nThis repo is **single-context**: one root `CONTEXT.md` + `docs/adr/`.\n\n```\n/\n├── CONTEXT.md\n├── docs/adr/\n│   ├── 0001-seed-default-labels-once.md\n│   ├── 0002-blocking-graph-integrity.md\n│   ├── 0003-audit-columns-and-editability.md\n│   └── 0004-append-only-events-log.md\n└── ...\n```\n\n(For reference, a multi-context repo would instead have a `CONTEXT-MAP.md` at\nthe root pointing at per-context `CONTEXT.md` files under `src/<context>/`, each\nwith its own `docs/adr/`.)\n\n## Use the glossary's vocabulary\n\nWhen your output names a domain concept (in an issue title, a refactor proposal,\na hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift\nto synonyms the glossary explicitly avoids.\n\nIf the concept you need isn't in the glossary yet, that's a signal — either\nyou're inventing language the project doesn't use (reconsider) or there's a real\ngap (note it for `/domain-modeling`).\n\n## Flag ADR conflicts\n\nIf your output contradicts an existing ADR, surface it explicitly rather than\nsilently overriding:\n\n> _Contradicts ADR-0002 (blocking graph is a strict DAG) — but worth reopening\n> because…_\n",[],[322,655,665],"cd331766-78b4-42ac-9bab-23a92d686f0f",["D",1784077088196],[],[322,655,32],"8a26a61d-d596-4a29-9050-a96215f95442",136,["D",1783641873401],[351,352,353,354],[322,655],"31c02dd3-aedd-4960-bc34-e9b9c5426093","0004-append-only-events-log.md","ee7eb5c6-7bf2-11f1-8930-1607ee4eb77e","ee2551f2-7bf2-11f1-a4f1-1607ee4eb77e",168,["D",1783653142026],"# 0004 — Single append-only events log as source of truth for history\n\n## Status\n\nAccepted\n\n## Context\n\nAudit columns (ADR 0003) record only the _last_ writer of a row — they cannot\nanswer \"what happened to this issue over time,\" and crucially cannot recover\ninformation that a mutation _removed_ (a label unapplied, an assignee dropped, a\nblock edge deleted). We want both an audit trail and full state history, and\noptionally a GitHub-style activity timeline later.\n\n## Decision\n\nAdd one append-only, polymorphic table:\n\n```\nissue_tracker_events(\n  id              INTEGER PK,\n  event_type      TEXT,      -- \"<entity>.<verb>\"\n  entity_id       INTEGER,   -- id of the issue/comment/label\n  actor           TEXT,      -- Val Town handle who did it\n  data            TEXT,      -- JSON, shape depends on verb\n  event_timestamp INTEGER\n)\n```\n\n- **Entities**: `issue`, `comment`, `label`. **Verbs**: `created`, `updated`,\n  `deleted`.\n- **Grammar** — _boundary events snapshot, updates carry deltas_:\n  - `*.created` → full initial-state snapshot in `data`.\n  - `*.deleted` → full final-state snapshot in `data` (entities are\n    **hard-deleted**; the event is the tombstone — see ADR 0003 amendment /\n    soft-delete rejected).\n  - `*.updated` → `{ update_target, from, to }`.\n- **Associations have no entity type of their own.** Applying/removing a label,\n  assigning/unassigning a user, and adding/removing a block edge are modelled as\n  `issue.updated` events with `update_target` ∈ {`label`, `assignee`, `blocks`,\n  `blocked_by`} and `from`/`to` using **`null ↔ value`** (null→X = added, X→null\n  = removed). This reuses the scalar-edit grammar; no new verb, no link entity\n  type.\n- **One event per changed field.** Closing emits two events (`status`\n  open→closed and `state_reason` null→reason) sharing one\n  `actor`/`event_timestamp`; reopen likewise. Rendering \"closed as not planned\"\n  as a single timeline line is a read-time grouping by (actor, timestamp).\n- **Block edges write one event, on the acting issue** (ADR 0002 / Q17); the\n  reverse \"blocked by\" view is derived by querying events whose `to` references\n  the issue.\n\n## Consequences\n\n- The log is the single source of truth for provenance and history; live tables\n  hold only current state. Every entity create/update/delete and every\n  association change **must** emit an event, or provenance is lost.\n- Full state at any past time is reconstructable: start from the `created`\n  snapshot, replay `updated` deltas forward.\n- Removals are captured (the whole point) — a `label_removed`-style fact\n  survives as an `issue.updated` with `to: null`, and deleted entities leave a\n  snapshot tombstone.\n- Whether the log is surfaced in the UI (activity timeline) is deferred; the\n  data supports it either way. Auditability is derived, not a stored view.\n- The table grows unboundedly (append-only); pruning/retention is a future\n  concern.\n",[],[322,690,682],"adr","26aa1419-2852-4924-b2b1-f3eb9e4adc9e","0003-audit-columns-and-editability.md","ee76ee18-7bf2-11f1-8022-1607ee4eb77e",166,["D",1783653141647],"# 0003 — Audit columns and universal editability\n\n## Status\n\nAccepted — **partially superseded by ADR 0004** (see amendment at end). The\n_editability_ decision stands in full; the `*_by` columns and the link\ncreation-pair were removed once the events log (ADR 0004) became the source of\ntruth for provenance.\n\n## Context\n\nWe want to know who created and last changed every piece of user-authored data,\nand we want a uniform convention rather than ad-hoc timestamps per table. Today\nit is inconsistent: issues have `created_by`/`created_at`/`updated_at` but no\n`updated_by`; comments have only `author` + `created_at` and no edit operation\nat all.\n\n## Decision\n\nTwo rules, applied across the whole schema:\n\n1. **Entities carry all four audit columns**: `created_at`, `created_by`,\n   `updated_at`, `updated_by`. Entities are the things a user authors and can\n   later change — **Issue**, **Comment**, **Label**. Consequently, _every entity\n   is editable_ (there is an update operation for each), including comments.\n   `created_by`/`updated_by` hold Val Town handles.\n\n2. **Join / link rows carry only the creation pair**: `created_at` +\n   `created_by` (surfaced with intent-revealing names, e.g.\n   `assigned_at`/`assigned_by` on assignees, `linked_at`/`linked_by` on block\n   edges). Links are immutable — a user _adds_ or _removes_ them, never _edits_\n   one — so `updated_at`/`updated_by` would be meaningless.\n\nNaming: the Comment's `author` column is renamed **`created_by`** so the\nconvention is uniform (the author _is_ the creator).\n\n## Consequences\n\n- Comment editing becomes a real, supported operation (mirrors GitHub).\n- Every table's provenance is queryable in a uniform way; no per-table special\n  cases.\n- `updated_at` combines with the \"touch\" rule (see CONTEXT.md): association\n  changes bump the parent issue's `updated_at` too.\n- Slightly more columns and write-path bookkeeping everywhere — accepted for the\n  auditability and uniformity it buys.\n\n## Amendment (superseded in part by ADR 0004)\n\nOnce the append-only events log (ADR 0004) was adopted, it became the source of\ntruth for _who_ did _what_ and _when_. That makes the `*_by` columns redundant —\nactor is derivable as the latest event for an entity. We therefore revised this\ndecision:\n\n- **Entities keep only `created_at` + `updated_at`** as denormalized columns —\n  they drive hot-path listing and \"last activity\" sorting, which would otherwise\n  require a `MAX(event_timestamp)` aggregate over the log on every render.\n- **`created_by` / `updated_by` columns are dropped.** The actor is derived from\n  the events log, which is already loaded on the only screen that needs it (an\n  entity's detail/timeline view).\n- **Link rows carry no audit columns at all** — assignees and block edges become\n  bare relationship tuples; their provenance lives entirely in events.\n\nWhat stands unchanged from the original decision: **every entity (Issue,\nComment, Label) is editable**, including comments, and the Comment's old\n`author` column is gone (its creator is derived from the `comment.created`\nevent).\n",[],[322,690,692],"bf1eb092-9651-471a-b7da-df0287561a70","0002-blocking-graph-integrity.md","eedbe340-7bf2-11f1-a9f4-1607ee4eb77e",183,["D",1783653141615],"# 0002 — Blocking graph is a strict DAG (reject all cycles)\n\n## Status\n\nAccepted\n\n## Context\n\nIssues can block each other, forming a directed graph stored as edges in\n`issue_tracker_issue_blocks(blocker_id, blocked_id)` (edge direction: blocker →\nblocked). Such a graph can contain degenerate or cyclic edges:\n\n- **Self-edge** — A blocks A.\n- **Direct reciprocal** — A blocks B and B blocks A.\n- **Longer cycle** — A blocks B, B blocks C, C blocks A.\n\nGitHub, empirically, rejects self-edges and direct reciprocals but _allows_\nlonger cycles like A→B→C→A (verified against its GraphQL `blockedBy`/`blocking`\nAPI). We deliberately do **not** follow GitHub here.\n\n## Decision\n\nEnforce a strict DAG — reject **any** edge that would create a cycle. All three\ncases above collapse into one rule, checked on insert of edge\n`blocker → blocked`:\n\n> Reject if `blocked` can already reach `blocker` by following block-edges —\n> i.e. a path `blocked → … → blocker` already exists (a self-edge is the\n> degenerate `blocked == blocker` case).\n\nImplemented as a reachability query (SQLite `WITH RECURSIVE`) run in the\ndatabase on each insert. `UNIQUE(blocker_id, blocked_id)` additionally prevents\nduplicate edges.\n\n## Rationale\n\nA cycle in a dependency graph is logically incoherent: a loop of issues that can\nnever be satisfied in dependency order. Keeping the graph a strict DAG also\npreserves the option to add topological \"what's workable now\" ordering later\nwithout retrofitting cycle detection.\n\n## Consequences\n\n- Every edge insert pays for one reachability traversal. For a\n  personal/small-team tracker's graph size this is negligible, and it runs\n  entirely in SQLite.\n- The block graph is guaranteed acyclic, so downstream features may safely\n  assume a topological order exists.\n- This is stricter than GitHub; anyone porting expectations from GitHub should\n  know that A→B→C→A is refused here.\n",[],[322,690,700],"610774cf-6c90-4bf8-91cb-2b82abfa3ecc","0001-seed-default-labels-once.md","ee84afa8-7bf2-11f1-8022-1607ee4eb77e",167,["D",1783653141936],"# 0001 — Seed default labels once, at table creation only\n\n## Status\n\nAccepted\n\n## Context\n\nThe tracker is a drop-in library: `initSchema()` is idempotent and runs on\n**every request** to guarantee the host val's tables exist. We also want to ship\na curated set of default labels (`bug`, `enhancement`, `documentation`,\n`question`, `duplicate`), and labels are user-deletable.\n\nThese two facts collide. If defaults are inserted \"when missing\" inside the\nper-request `initSchema()`, then any default a user deliberately deletes will\nreappear on the very next request — deletion would be impossible for default\nlabels.\n\n## Decision\n\nSeed the default labels **exactly once, in the branch that creates the\n`issue_tracker_labels` table** (i.e. only when it did not previously exist).\nOnce the table exists, `initSchema()` never touches label _rows_ again. After\ncreation the label set belongs entirely to the user: deletes and edits are\npermanent.\n\n## Consequences\n\n- Default labels behave like a starting kit, not enforced state — users can\n  prune or rename any of them and the changes stick.\n- The \"table was just created\" signal must be detected explicitly (e.g. check\n  existence before `CREATE TABLE`, or seed only when a freshly created table is\n  empty on first creation), since `CREATE TABLE IF NOT EXISTS` alone doesn't\n  tell us whether it already had data.\n- A host that wants the defaults back after deleting them must re-add them\n  manually; there is intentionally no auto-heal.\n",[],[322,690,708],"12a719bc-c079-4db1-bbdb-e6251ba56110",135,["D",1783641873285],[346,347,348,349],[322,690],["D",1783635592340],[345,350,355,370,371],[322],["D",1784077087867],[],[328],["D",1783563523910],["D",1789525245864],{"_98":97,"_105":101},{"_98":97,"_99":-5,"_100":101,"_18":53,"_102":103,"_104":24},{"_13":87,"_31":88,"_41":40,"_89":42,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":-5,"_95":43,"_96":97},"ctx",{"_80":-5,"_125":764,"_765":766,"_767":768,"_769":24,"_770":24,"_771":24,"_772":57,"_773":-5,"_774":-7,"_775":-7,"_776":61,"_777":24,"_778":24,"_779":-5,"_780":24,"_781":24,"_782":24,"_783":-5},"ENV",{"_735":736,"_737":738,"_739":88,"_740":741,"_742":743,"_744":745,"_746":747,"_748":749,"_750":751,"_752":753,"_754":755,"_756":757,"_758":759,"_760":761,"_762":763},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]
</article></body></html>

Diff · v316