From 3d42c64238d9de57d7b9a4ab474d37e5f93ea630 Mon Sep 17 00:00:00 2001 From: Hare Date: Sat, 30 May 2026 15:29:34 +0900 Subject: [PATCH] docs: create stale docs refresh ticket --- .../artifacts/.gitkeep | 0 .../item.md | 46 +++++++++++++++++++ .../thread.md | 22 +++++++++ 3 files changed, 68 insertions(+) create mode 100644 work-items/open/20260530-062852-refresh-stale-docs/artifacts/.gitkeep create mode 100644 work-items/open/20260530-062852-refresh-stale-docs/item.md create mode 100644 work-items/open/20260530-062852-refresh-stale-docs/thread.md diff --git a/work-items/open/20260530-062852-refresh-stale-docs/artifacts/.gitkeep b/work-items/open/20260530-062852-refresh-stale-docs/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/work-items/open/20260530-062852-refresh-stale-docs/item.md b/work-items/open/20260530-062852-refresh-stale-docs/item.md new file mode 100644 index 00000000..4303757b --- /dev/null +++ b/work-items/open/20260530-062852-refresh-stale-docs/item.md @@ -0,0 +1,46 @@ +--- +id: 20260530-062852-refresh-stale-docs +slug: refresh-stale-docs +title: Docs: refresh stale architecture and operation docs +status: open +kind: task +priority: P2 +labels: [docs, maintenance] +created_at: 2026-05-30T06:28:52Z +updated_at: 2026-05-30T06:29:24Z +assignee: null +legacy_ticket: null +--- + +## Background + +Read-only docs audit Pod `docs-stale-audit-20260530` reported that several high-level docs still describe older protocol/session/tool/TUI behavior. The stale content is concentrated in architecture, compaction, TUI keybindings, and older plan documents. + +The current authoritative sources are the code, `work-items/`, `KNOWN_ISSUES.md`, `AGENTS.md`, and git history. `docs/report/` remains historical observations, not current spec authority. + +## Scope + +Update or clearly demote stale docs so readers do not mistake old plans for current behavior: + +- `docs/architecture.md` + - Refresh Protocol Method/Event overview. + - Refresh session persistence description for current `session_id` / `segment_id` / `SegmentOrigin` / Pod metadata split. + - Refresh built-in tools description beyond only file tools. + - Clarify the coarse `1 Pod = 1 process = 1 session` statement after Pod metadata / session / segment separation. +- `docs/compaction.md` + - Refresh compact/session/segment descriptions to match current session-store and segment semantics. +- `docs/tui-keybindings.md` + - Refresh `Ctrl-R` behavior and current command/queue/completion controls. +- `docs/plan/llm_presistence.md` + - Mark as superseded/archival or replace with current-session persistence pointers. +- `docs/plan/ai-maintainer.md` + - Replace old `TODO.md` / `tickets/` authority language with current `tickets.sh` + `work-items/` operation. + +## Acceptance criteria + +- High-priority stale claims from the docs audit are either corrected or explicitly marked historical/superseded. +- Updated docs consistently describe current Pod metadata vs session-store vs runtime registry responsibilities at a high level. +- Updated docs do not claim `TODO.md` / legacy `tickets/` are the active work-item authority. +- Updated docs do not claim `Ctrl-R` is removed; TUI keybindings reflect current behavior sufficiently for users. +- No generated report/history document is rewritten as if it were current spec authority. +- `./tickets.sh doctor` and `git diff --check` pass. diff --git a/work-items/open/20260530-062852-refresh-stale-docs/thread.md b/work-items/open/20260530-062852-refresh-stale-docs/thread.md new file mode 100644 index 00000000..35c4fc61 --- /dev/null +++ b/work-items/open/20260530-062852-refresh-stale-docs/thread.md @@ -0,0 +1,22 @@ + + +## Created + +Created by tickets.sh create. + +--- + + + +## Plan + +Implementation plan: + +1. Read the current target docs and authoritative code/type definitions. +2. Update high-level docs in-place, keeping edits scoped to stale claims rather than broad prose rewrites. +3. Mark superseded plan docs clearly when replacing them would be larger than useful. +4. Validate with `./tickets.sh doctor` and `git diff --check`. +5. Review the resulting diff against the audit findings before closing. + + +---