Repository navigation
docs: Compact the developer docs and drop unreferenced PR assets - #1093
Conversation
omesser
left a comment
There was a problem hiding this comment.
Soft-gate (Architect) — value preservation
Verdict: CLEARED with Softs
Tip verified: 02f3bb0a7301b4b7cc261d99fd108aa3b76ce2e0
Primary Hard axis (Oded): nothing of current import and value is lost. Docs compaction + ~10 MB asset delete. Checked DEVELOPMENT levers before→after vs base 6a496b1e; DESIGN/SPEC Capture/Windows/ADR-0024/0032 against code+ADRs; grepped deleted paths; compared cite edits to #1092.
Hard findings
None. No still-used command, env var, default, or procedure vanishes from DEVELOPMENT. DESIGN/SPEC Capture-drop, Windows-not-deferred, and ADR-0024/0032 alignment match living ADRs/code. Deleted docs/pr/, docs/pr-assets/, named docs/readme/*.png, and docs/research/naming-review-2026-09.md have zero living tree refs (permalinked PR bodies by SHA excluded as claimed). CONTEXT.md and docs/design/ untouched; research/ rest kept.
DEVELOPMENT levers (Hard 1)
- Every
FIDGET_*token from base still present; Trace Variables duplicate tables merged without dropping a row (FIDGET_TRACE_WINDOWSkept in the unified table). - Shell command set preserved (comment/whitespace only). Signing procedure kept under Keyring (
scripts/dev-sign.sh+ Keychain ACL). - Broken
FIDGET_CAPTURABLEparagraph fixed to ADR-0024 semantics; reply-contract archived link now pins ignored test + pre-#135 README SHA. - MCP tool catalog deferred to README
#harness--mcp(still listsspeak/play_behavior/ sensing / Memory + resources). Defaults (30s / 120 / 60 / 1024|8192 /gpt-4o-mini/ data-folder paths) still stated.
DESIGN / SPEC (Hard 2)
- Diagram Capture boxes gone; Sensing is titles/app under consent; Dropped section cites ADR-0031.
- Windows no longer deferred (ships NSIS; stub/degraded cells remain). SPEC scope line: "Voice is deferred" only.
- Screen-share story → Presence opt-out + ADR-0024; "Window titles deferred" removed; titles+app names under one consent (ADR-0032). Character count "two shipped" → "at least two styles" / eight ship in README — accurate.
Deleted paths (Hard 3)
git grep on tip: no hits for docs/pr/, docs/pr-assets/, naming-review, or deleted readme PNG basenames.
Overlap with #1092 (Hard 4)
ADR cite renumbers on shared DESIGN/SPEC lines match #1092 (0014→0020, drop "supersedes 0005", 0017→0022, non-loopback→0023). Compatible in spirit; DEVELOPMENT prose compaction will Soft-conflict with #1092's lighter cite-only edits (incl. Related-decisions section this PR drops — #1092's Soft (b) ADR-0010 residual is already ADR-0023 here).
Soft ledger
| Item | State | |
|---|---|---|
| (a) | CI on tip | Met — checks ubuntu/mac/windows + Pages build green; deploy skipped |
| (b) | Mergeable vs current main (ded07cf…) |
Open — mergeable_state: dirty. Real conflict only in docs/DEVELOPMENT.md Reply Contract Measurements (this tip's pinned SHA/ignored-test fix vs main's still-broken "archived lines 450–490" after #1087 rename). DESIGN/README auto-merge cleanly with #1087/#1089. Soft rebase keeping this tip's side |
| (c) | Dirty vs #1092 (also dirty vs main) | Open — both open and dirty; cite renumbers align, but DEVELOPMENT compaction vs #1092 cite-only + Related-decisions update will need a Soft rebase whichever lands second |
Merge / draft
- Draft: no
- Mergeable: CONFLICTING / dirty vs current main (base-at-open
6a496b1e) - CI: green on tip
One-liner for Oded
Value preservation holds: every kept DEVELOPMENT lever and live DESIGN/SPEC constraint survives the compact+delete; Softs are a one-hunk rebase vs main and sequencing with #1092.
Babysit: none yet.
— Cursor agent (Architect), on @omesser's behalf.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
02f3bb0 to
0f53d66
Compare
omesser
left a comment
There was a problem hiding this comment.
Soft-gate (Architect) — value preservation (re-gate after tip push)
Verdict: CLEARED with Softs
Tip verified: 0f53d664a498655cefd3529fff8ef3ad6b56af98
Note: Already MERGED by @omesser at 2026-09-28 04:00:49 IDT as b855b898… (main tip now 72028496… via later #1102). This re-gate is historical Soft-ledger update on the tip that landed.
Primary Hard axis (Oded): nothing of current import and value is lost. Re-verified on new tip after rebase + "docs: Address review round 1" vs PR base 694d9f99…. Round-1 restores and sibling overlap with open #1092 checked.
Hard findings
None. DEVELOPMENT levers (every base FIDGET_*, commands, signing/keyring, defaults 30s/120/60/1024|8192/gpt-4o-mini/data-folder, MCP catalog → README #harness--mcp) preserved. DESIGN/SPEC Capture-drop (ADR-0031), Windows-not-deferred, ADR-0024/0032 consent stories accurate; stale "two shipped Characters" gone (now "at least two styles"). Deleted docs/pr/, docs/pr-assets/, and six docs/readme/*.png have zero living-tree refs. docs/research/naming-review-2026-09.md restored with shipped preamble. Round-1: domain.md proceed-silently restored; DND/Sound under Settings; verify-overlay.sh → docs/DEVELOPMENT.md; #594 image pinned to 3d16d6fc.
DEVELOPMENT levers (Hard 1)
- Tip vs base: no
FIDGET_*token lost (FIDGET_BENCH_*still named via reply-contract ignored-test note). Trace / Completer / Harness / MCP vars and defaults still stated. - Shell command set +
scripts/dev-sign.shKeychain ACL procedure kept. MCP tool list defers to README#harness--mcp(livespeak/play_behavior/ sensing / Memory catalog).
DESIGN / SPEC (Hard 2)
- Capture tiers dropped with ADR-0031 cites; screen-share = capturable-by-default + Presence opt-out (ADR-0024); titles+app names under one consent (ADR-0032).
- Windows ships (NSIS); no "Windows deferred". Character copy is style-span, not "two shipped".
Deleted paths + Round-1 restores (Hard 3 / 5)
git grepon tip: nodocs/pr/,docs/pr-assets/, or deleted readme PNG basenames.- naming-review present + "Shipped: … #1079" preamble; domain proceed-silently present; verify-overlay checklist lines name
docs/DEVELOPMENT.md.
Overlap with #1092 (Hard 4)
ADR numbers on tip match living ADRs; no incompatible renumber vs #1092 tip 268aba23…. #1092 remains OPEN / CONFLICTING / DIRTY vs post-merge main — expected Soft DEVELOPMENT conflict (Director env table + MCP "How it works"); resolve keeping this PR's compacted text (citations already aligned). Cite-compat Soft; sequencing Soft remains.
Soft ledger
| Item | State | |
|---|---|---|
| (a) | CI on tip | Met — checks ubuntu/macos/windows SUCCESS; Pages build SUCCESS; deploy SKIPPED (OK) on run 36364263977 / 36364263990 |
| (b) | Mergeable vs current main |
Met — tip rebased onto main after #1085/#1087/#1089; merged cleanly as b855b898… (prior Soft dirty Reply-Contract hunk cleared by rebase) |
| (c) | Sequencing / dirty vs open #1092 | Open — #1092 tip 268aba23… still CONFLICTING/DIRTY vs main that now includes this PR; ADR cites compatible; DEVELOPMENT Soft-conflict remains for whoever rebases #1092 |
Merge / draft
- Draft: no
- Mergeable: already MERGED (was MERGEABLE/UNSTABLE while CI settled)
- CI: green on tip
One-liner for Oded
Value preservation still holds on 0f53d664… after round-1 restores; Soft (b) cleared by the rebase and the PR is already merged — only Soft left is #1092 rebasing onto post-#1093 main.
Babysit: stop (merged). Hand #1092 Soft rebase to Coder if desired.
— Cursor agent (Architect), on @omesser's behalf.
Why
The docs had grown restatements, narrative history, and stale claims. The stale ones: Capture boxes in the design diagram, "two shipped Characters", Windows listed as deferred, and a checklist item that contradicts capturable-by-default.
docs/pr/anddocs/pr-assets/also held about 10 MB of one-off PR screenshots that nothing references.What changed
docs/DEVELOPMENT.mdFIDGET_CAPTURABLEparagraph and a checklist ref to nonexistent items 24–27 fixed. The dead "archived README lines 450–490" link now names the ignored test and pins the pre-#135 README. The MCP tool list defers to the README catalog. The cursor-agent, probe, and BYO prose is compacted. Every command, env var, and default stays.README.md(after the opening)in progresslegend.DESIGN.mddocs/SPEC.mddocs/agents/*.mddomain.md, dated history inpicking-work.md,writing.md, andcomments.md.docs/pr/,docs/pr-assets/, 6docs/readme/PNGsblob/main/docs/pr/441-bubble-ceiling.png; its body now pins that link to3d16d6fc.docs/research/naming-review-2026-09.mddocs/agents/docs.md).scripts/verify-overlay.shdocs/DEVELOPMENT.mdinstead of the README (#1094).Left alone:
docs/research/. Research stays pinned to the tree it read (docs/agents/docs.md).docs/design/andspike/: out of scope for this PR.omesser/ai-buddyURLs, which fix: Point forge coordinates at omesser/fidget #1087 owns.CONTEXT.md, which has no duplicates.The ADR citations here already match #1092's replacement links for the ADRs it removes, and none point at a removed ADR. #1092 renumbers nothing. After either PR merges, the other conflicts in
docs/DEVELOPMENT.md(the Director env table and MCP "How it works"). Resolve by keeping this PR's text; its citations are the same as #1092's.Review round 1
mainafter fix: Freeze the quick-message pill when chat cannot answer #1085, fix: Point forge coordinates at omesser/fidget #1087 and docs(agents): Ask before taking over the GUI, and seed an e2e scenario library #1089 merged.CONTEXT.md).naming-review-2026-09.mdwith a shipped preamble.docs/agents/domain.md.3d16d6fc.verify-overlay.shchecklist pointers.How to verify
node --test tests/(432 pass, 0 fail)pre-commit run --fileson every touched fileDEVELOPMENT.md#…anchor in touched files resolvesgit grepfinds no reference to a deleted file— Claude Code agent, on @omesser's behalf.
🤖 Generated with Claude Code