tommy0103
676ce940dd
External PRs here have consistently arrived lint-clean, typechecking, and green on their own tests, then stalled on the same handful of causes: a capability advertised in the description but unreachable in code, assertions written against the implementation rather than the requirement, destructive migrations that cannot resume after an interruption, concepts reinvented next to an existing one, transcript content treated as trusted, and verification run against a head that a later merge invalidated. Generic style rules would not have caught any of those, so CONTRIBUTING.md states them directly, alongside hard per-area constraints for the renderer/Electron, provider adapter, schema migration, main process, and indexing/daemon boundaries. The PR template mirrors those as collapsible per-area checklists so a renderer change is not asked about tokenizer migrations, and gives deliberately-out-of-scope work its own place above the fold rather than leaving it as a caveat inside a shipped diff. README points at the document and repeats the four rules worth knowing before reading it.
5.0 KiB
5.0 KiB
What and why
Closes #
Verification
npm test—npm run typecheck— 0 errors (root + app)npm run lint— 0 errorsnpm run test:electron:all—- New tests actually run in CI (
.github/workflows/) - No existing assertion was loosened
- Every capability described above was exercised end to end from the outermost entry point (including anything shown in a screenshot)
- Re-ran the checks above on the current head, after the most recent merge
Deliberately out of scope
Renderer / Electron UI — expand if you touched app/src/renderer or row rendering
- Reader-anchor assertion added — content settling above the viewport does not move the row the user is looking at
- Async media covered at mount, size-available, and load/error — not only the final state
- Tested both at rest and mid-scroll (
virtual-coreskips compensation for measured rows when scrolling backward) - No
loading="lazy"on virtualized rows - No hardcoded colors or type sizes in shadow DOM (
var(--muted)etc.) - One visual treatment per user-visible concept
- Library calling conventions either accept both shapes or are pinned in code
- Every renderer probe has a deadline and an
error→ reject path - No assertion with sub-pixel headroom (self-calibrate instead)
Provider adapter — expand if you touched packages/core/src/providers
- Read
claude.ts,codex.ts, andkimi.tsin full first - Session identity is composite (e.g. normalized cwd + header id), not the source id alone
- A test actually calls
discover()against each supported directory layout - Directory layout verified against upstream source or format docs
- Canonical transcript invariant holds: direct assembly == SQLite round-trip (ADR-0007)
- Text-less records (image-only, aborted-with-usage) still emit a row
indexVersionMarkerbumped if uuid format, role normalization, or any stored-row shape changed- "Should not be displayed" uses
visibility, not a new meaning foris_sidechain - Cursor detects same-millisecond rewrites (mtime + ctime + size + inode)
- Unknown/newer versions are skipped and recorded, not thrown on
Schema / migration — expand if you touched schema.sql or schema-migrations.ts
schema.sqlhash updated intests/provider-schema-stability.test.mjs, with justification above- Destructive DDL runs inside
runWriteTransaction - Completion is not inferred from the target state's own name — interrupting at any line self-heals on the next start
- Validation rejects anything SQLite would reject, before any mutation
- Checked that no table carries its own arguments that a blanket write would erase
- External input spliced into DDL has an allowlist and an injection test
Main process / untrusted input — expand if you touched app/src/main
- Transcript-derived paths do not reach
shell.openPathunguarded; confirmation dialogs default to Cancel - File reads triggered by transcript content are allowlisted to known roots
- No
innerHTML/ detached<textarea>decoding of untrusted text; decode exactly once, escape on output, pinned by a test - No synchronous IO in the main process
- Interception scope not broadened beyond this feature
- New main/preload sources are
.ts(ADR-0005)
Indexing / daemon — expand if you touched indexer.ts, provider-indexing.ts, or write coordination
- Read-only while the daemon heartbeat is fresh — no write connection, migration, PRAGMA change, checkpoint, or indexing
- Anything needing periodic refresh has a refresh point that is genuinely called repeatedly, including on existing installations
- Configuration mismatch under
daemon_activeis an explicit error, not a silent fall back to a stale index - Trigger vs. full-rebuild choice is justified above