Skip to content

docs: code is the source of truth; user-facing README and Help - #347

Merged
mdiener21 merged 4 commits into
mainfrom
docs/code-is-source-of-truth
Nov 17, 2026
Merged

mdiener21 merged 4 commits into
mainfrom
docs/code-is-source-of-truth

Conversation

@mdiener21

Copy link
Copy Markdown
Owner

Summary

The code is the source of truth. Docs that disagreed with it are corrected, and specs no longer gate PRs.

 .github/workflows/
-  spec-sync.yml                 # blocked PRs without docs/spec + CHANGELOG edits (and never fired: it checked src/, not client/src/)
 scripts/
-  check-spec-sync.mjs
   prepare-release.mjs           # badge regex fixed: README badge was stuck at 3.2.0
 docs/
-  ai-workflows/                 # stale SOPs, broken skill pointers
-  codebase/codebase.txt         # stale generated file list
   adr/0003, 0004, 0005          # corrected against the code
   user/help-how-to.md           # mirrors the in-app Help
 AGENTS.md                       # + AI development workflow, + releases, specs = short reference
 CONTEXT.md                      # 5 inaccuracies that would lead to wrong code
 README.md                       # rewritten for users; developer setup lives in AGENTS.md
 client/src/index.html           # Help modal + footer: what users can do, no "localStorage"

AI development workflow (AGENTS.md):

feature   grill-with-docs? → to-prd → to-tickets → implement-spec (tdd per ticket, code-review)
small     tdd → PR
bug       diagnosing-bugs → tdd (failing test first)
refactor  improve-codebase-architecture → to-tickets → implement-spec

ADR and CONTEXT corrections, each checked against the code:

  • ADR-0003: global settings are written by settings.updated events (scope global); saveGlobalSettings is gone.
  • ADR-0004: 36 event types, PocketBase hooks and indexes, GC only after the 30-day grace window, store layout, legacy-collection lock state.
  • ADR-0005: status is implemented; the write path is ingestEvent → projector; the known sole-writer exceptions are listed (addBoard, removeBoard, saveSettings, boot migration).
  • CONTEXT.md:
    • Board settings live in kv.
    • The sole-writer exceptions are named.
    • BOARD_CHANGED is marked unused.
    • The event-type list points at EVENT_TYPES.
    • The envelope example uses task.updated (there is no task.priority_changed).

Evidence

  • Spec Sync before: passed PR feat(board): open desktop controls menu as a right-side panel #344 while printing "No files under src/ changed" although client/src/kanban.js had changed.
  • Badge regex: the old pattern never matched the README badge. The new one turns version-3.4.24-brightgreen into version-9.9.9-brightgreen (node check).
  • Help modal: rendered and checked at 1280×900.
  • Checks: npm run lint clean; board-mobile-bottom-bar.spec.ts 19/19 (it opens Help).

Merge Danger

Door: two-way

Docs, one HTML help block and one regex. Removing the Spec Sync workflow is a revert away; main has no branch protection, so no required check refers to it.

Blast Radius: docs

The in-app Help mentions "Esc closes the controls panel". That is true once #344 merges.

🤖 Generated with Claude Code

mdiener21 and others added 4 commits November 17, 2026 15:43
- Remove the Spec Sync check; docs/spec/ is short reference, updated as
  needed and never a gate
- AGENTS.md: AI workflow on the to-prd / to-tickets / implement-spec / tdd
  skills, release notes, user-facing one-line changelog rule
- Delete docs/ai-workflows/ and docs/codebase/; copilot-instructions.md
  points at AGENTS.md
- ADR-0003/0004/0005 and CONTEXT.md corrected against the code
- README rewritten for users; in-app Help and footer list what users can do
- Fix the README version badge regex in prepare-release.mjs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… index

- docs/readme.md is now a short index with working links
- boards/labels guides point at ../example-boards and drop missing files
- keybindings lists the controls-panel Esc and the time-tracking shortcuts
- specification-kanban.md is a spec list, not a must-update policy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mdiener21
mdiener21 merged commit 0de0173 into main Nov 17, 2026
15 checks passed
@mdiener21
mdiener21 deleted the docs/code-is-source-of-truth branch November 17, 2026 16:19
@mdiener21
mdiener21 restored the docs/code-is-source-of-truth branch November 20, 2026 11:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant