Plan wiki ticket ui ia

Current — the latest status report. Reports freeze once published; corrections appear in later reports.

WikiTicket UI — IA-aware project status dashboard (new repo ../wiki_ticket_sdd_ui)

Supersedes: 2026-07-21-wiki-ticket-ui (epic 01KY111BC7PABV8W6SDNVQACSN; its 7 items were cancelled in favor of this plan's items). That plan was written before the IA & content model epic (#93, PR #104, plus follow-ups #109–#112) shipped. The IA work changed the ground the UI stands on: the repo now publishes a committed, deterministic, machine-readable index of every document, its identity, its truth state, and the full traceability graph. Roughly half of what the old plan told the UI to derive is now provided — and the parts of its data contract describing the ledger, the roadmap header, and doc frontmatter are simply wrong now. This plan is the same product with a corrected foundation: same repo, same tech stack, same panels where nothing changed, plus one new panel the IA work makes possible.

Context

WikiTicket SDD stores everything as files in the tracked repo. The original UI plan (2026-07-21) designed a read-only dashboard over that repo: a local web app (Hono JSON API + Vite/React front end, Tauri later) that works against ANY repo with worklog installed. All of that stands. Status: plan only — the build starts when Rick says go, unchanged from the original.

What changed since 2026-07-21: the IA & content model shipped. Its deliverables are now committed fact in every worklog repo at this version:

• docs/.index/ — a generated, committed, byte-deterministic index plane. Pure function of the repo's committed files (no wall clock, no git calls), regenerated by bin/worklog ia-index, CI-checked for freshness. Contents:
  • _inventory.json — every document with its wiki_key (stable identity), canonical_key, aliases, doc_type, truth_state, lifecycle status, title, supersedes/superseded_by links, and validation problems.
  • _graph.json — the full traceability graph: typed edges (produces, belongs-to, targets, references, lands-in, supersedes, snapshot-of, relates-to) connecting plans ↔ items ↔ tickets ↔ PRs ↔ releases ↔ ADRs.
  • publish-manifest.json — the publish plane: every wiki page with its page name, truth banner, render_hash, frozen flag, and the generated sidebar.
  • aliases.json + per-doc sidecar YAML files (metadata overlays for frozen docs).
• truth_state is a first-class axis — current / snapshot / superseded / archived, orthogonal to lifecycle status. Every wiki page carries a truth banner derived from it.
• Two-hash publish model — source_hash protects the frozen canonical source; render_hash (source + banner) drives the publish skip rule. Frozen-source drift is a detectable integrity violation (proven live: it caught a real post-publication edit, repaired in #109/#112-era work).
• Ledger (.work/published.json) entries grew fields: wiki_key, canonical_key, aliases, doc_type, truth_state, render_hash alongside the old rev/source/source_hash/url/title.
• docs/roadmap.md header is YAML frontmatter now (wiki_key, doc_type, truth_state, source_hash, generated_at) — no longer HTML comments.
• Frozen docs carry metadata in sidecars, not frontmatter. Parsing a frozen doc's file alone gives an incomplete record; the merged truth (frontmatter ∪ sidecar ∪ derived) is exactly what _inventory.json holds.
• New worklog commands: ia-index, ia-inventory, ia-render, ia-graph, trace-check, ticket-body, wiki-key.
• Schema boundary (PR #112): schema/doc.schema.json = documents, schema/entity.schema.json = graph entities (items today; releases/code-changes later). The UI's "docs" and "items" are formally different kinds of thing.

Impact on the UI, decision by decision

Unchanged (the original plan's core holds):

1. Generic by construction — target repo is runtime input; everything derived from .work/config.yml and the repo. Unchanged.
2. Never reimplement worklog semantics — shell out to bin/worklog. Unchanged, and now EXTENDED: never re-derive IA state either. Read docs/.index/* directly (it is committed, deterministic, and offline-friendly); shell out to bin/worklog ia-index only for freshness checks. The UI must not parse frontmatter to classify docs — gray-matter drops from the dependency list; _inventory.json replaces it.
3. Tech stack (Vite/React/TS/Tailwind/shadcn, Hono server, Tauri later). Unchanged.
4. gh CLI with unauthenticated REST fallback, graceful offline. Unchanged.
5. Read-only guarantee. Unchanged.
6. Repo layout, waves, dogfood-target verification. Unchanged.

Changed panels:

• Docs browser — now inventory-driven: list, classify, and badge documents straight from _inventory.json. Truth-state badges (current / snapshot / superseded / archived) replace the single "frozen" badge; supersede chains render as navigable links (the graph provides both directions). Validation problems from the inventory surface as per-doc warnings. Raw markdown still rendered with react-markdown; the frontmatter-chip idea survives but chips come from the inventory record, not from parsing the file.
• Wiki panel → Publish plane panel — joins three sources: publish-manifest.json (what SHOULD be published, with banners), .work/published.json (what IS published), and a live re-hash of sources. Drift is now three-way, mirroring the publish skill's own rules: green in-sync (render_hash match) / amber pending-republish (render_hash differs, source intact — e.g. a banner flipped) / red frozen-source drift (source_hash mismatch on a frozen page — integrity violation, "needs a human"). The old plan's single amber "stale" state cannot express the red case, which the IA work proved matters.
• Releases panel — snapshot linkage comes from the graph/inventory (truth_state == "snapshot", snapshot-of edges), not filename-pattern matching against docs/roadmap/<date>_<tag>-release.md.
• Roadmap panel — parse the YAML frontmatter header (not HTML comments) for source-hash/generated-at display.

New panel (the IA dividend):

• Traceability panel — render _graph.json: pick any node (plan, item, ticket, PR, release, ADR) and see its evidence chain both directions — plan → items → tickets → PRs → release; supersede chains across plans and ADRs. Surface trace-check output (closed items missing plan/ticket/PR links) as an integrity checklist. This is the wiki's Index-Traceability page made interactive — the single strongest argument for the UI existing at all.

Updated data contract (verified against the real repo, this session)

• Fold output, event envelope, sync-state.json: unchanged from the original plan.
• published.json: {wiki_key: {rev, source, source_hash(12-hex), render_hash(12-hex), url, title, wiki_key, canonical_key, aliases[], doc_type, truth_state}}.
• docs/.index/_inventory.json, _graph.json, publish-manifest.json, aliases.json: the four index-plane files above; committed, deterministic, safe to read directly.
• docs/roadmap.md: YAML frontmatter header (wiki_key: roadmap, doc_type, truth_state: current, source_hash, generated_at) + generated body with Mermaid.
• Frontmatter contract: per-type required subsets live in schema/doc.schema.json (documents) and schema/entity.schema.json (entities) — the UI treats these files as the authority if it ever needs to introspect, but normally consumes only _inventory.json.
• Server API additions over the old plan: /api/index/inventory, /api/index/graph, /api/index/manifest (thin file reads of docs/.index/*), and /api/trace-check (shells out).

Execution when Rick says go (NOT now)

Same three waves as the original: scaffold + server, parallel file-disjoint panels, polish/CI/tag. The traceability panel joins wave 2. Work tracked in the main repo's worklog (this plan's items); the UI repo is a deliverable, not a second tracker.

Immediate execution (this approval)

Store the plan only: worklog plan-capture (files the epic + items below, cancels the superseded plan's epic + 7 items), roadmap-render, ia-index, commit, publish, sync tickets. No repo creation, no code.

Verification (for the future build)

All four checks from the original plan, plus:

• Traceability panel: picking the ia-content-model plan shows its 9 items, their GitHub tickets, PR #104, and the supersedes link to wiki-information-architecture.
• Publish-plane panel: hand-edit a frozen source in a throwaway repo → red drift; flip a truth_state so a banner changes → amber pending; untouched → green.
• Docs browser: a doc whose metadata lives only in its sidecar (frozen legacy plan) still shows full identity chips — proof the UI reads the inventory, not the file.

Tasks

• (P2) Scaffold public repo wiki_ticket_sdd_ui: README, LICENSE, npm workspaces, CI Create the public repo with npm workspaces (server, web), CI running typecheck, build, and vitest. Unchanged from the superseded plan.
• (P2) Server: Hono JSON API over any worklog repo — fold, events, docs, index plane, git, gh, ledger, sync state The original API surface plus thin reads of docs/.index/_inventory.json, _graph.json, publish-manifest.json and a trace-check endpoint. Never re-derives worklog or IA semantics: shells out to bin/worklog, reads committed index files.
• (P2) Web shell: Vite + React + Tailwind dark dashboard chrome with repo picker Dark glassy shell, left nav, top bar with repo/branch/tag/drift indicators, recent repos remembered. Unchanged from the superseded plan.
• (P2) Panels wave 1: Overview, Board, Roadmap (Mermaid), Activity feed As in the superseded plan; Roadmap panel reads the YAML frontmatter header the IA work gave docs/roadmap.md instead of HTML comments.
• (P2) Panels wave 2: Releases, Docs browser (inventory-driven), Publish plane (3-way drift), Sync health, Charts Docs browser consumes _inventory.json with truth-state badges and supersede chains. Publish plane joins manifest + ledger + live re-hash into green/amber/red drift, mirroring the wiki-publish skill's own two-hash rules. Releases links snapshots via truth_state, not filename patterns.
• (P2) Traceability panel: interactive _graph.json explorer with trace-check integrity checklist Pick any node and walk plan → item → ticket → PR → release in both directions; supersede chains; trace-check gaps surfaced as an integrity checklist. New in this plan — the IA traceability graph made interactive.
• (P3) Polish pass to the visually-stunning bar; README screenshots; tag v0.1.0 Unchanged from the superseded plan.
• (P3) Tauri 2 desktop shell wrapping the same frontend Unchanged from the superseded plan; the API layer stays swappable for Tauri's Rust side without touching the UI.