docs(SPEC-033): privacy-respecting Pages visitor analytics - #41
Open
larryxiao wants to merge 2 commits into
Open
docs(SPEC-033): privacy-respecting Pages visitor analytics#41larryxiao wants to merge 2 commits into
larryxiao wants to merge 2 commits into
Conversation
larryxiao
force-pushed
the
docs/spec-028-pages-analytics
branch
from
May 16, 2026 22:28
248a6e9 to
afdf677
Compare
larryxiao
changed the title
larryxiao
added a commit
that referenced
this pull request
May 16, 2026
Renumbered from SPEC-029 — the dictation-distribution SPEC took the SPEC-028 slot on main, cascading SPEC-029 (Pages analytics, PR #41) and this SPEC up by one. SPEC-028 cross-references inside the file now point at SPEC-029 (Pages analytics) to match.
Renumbered from SPEC-029 — the local ANE-cache investigation SPEC took that slot. References to companion SPEC-030 (was: install count, now SPEC-032) updated accordingly.
larryxiao
changed the title
larryxiao
force-pushed
the
docs/spec-028-pages-analytics
branch
from
May 17, 2026 07:28
afdf677 to
a9bda90
Compare
…ID collision) SPEC-031 is already assigned to agent-kickoff (shipped) and SPEC-028 (the branch/body number) to dictation-distribution (merged). Renumber to the next free monotonic ID 033 and repoint the appcast cross-ref to SPEC-034 (#42). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
larryxiao
added a commit
that referenced
this pull request
May 31, 2026
… collision) SPEC-032 is already assigned to engine-prompt-token-cache and SPEC-029 (the branch/body number) to ane-cache-only-model. Renumber to the next free monotonic ID 034 and repoint the pages-analytics cross-ref to SPEC-033 (#41). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
larryxiao
changed the title
4 tasks
larryxiao
added a commit
that referenced
this pull request
May 31, 2026
Roadmap marked shipped work as spec-only and the spec index was missing 11 entries and listed shipped features as 'draft'. Reconcile both against main: - ROADMAP: SPEC-026 Sparkle + SPEC-011 update-flow corrected to their real state, SPEC-025 (signing/notarisation) marked the top adoption task with its blocker noted, demo-GIF scoped to the actually-missing artifact, and #62 re-transcribe-from-History added as a recovery-flow idea. - Spec index: rebuilt from disk (34 specs) with accurate implementation status (shipped / partial / draft / parked); reserves SPEC-033/034 for the renumbered docs PRs #41/#42. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
larryxiao
added a commit
that referenced
this pull request
Jun 8, 2026
ROADMAP's "Pending docs PRs" section already reserves SPEC-033 for PR #41 (Pages analytics) and SPEC-034 for PR #42 (active-install). The crash-sentinel spec was a stray 033; move it to the next free id 039: - rename SPEC-033-crash-sentinel-bug-report.md → SPEC-039-… - update the 4 SPEC-033 code comments in OpenQuackApp.swift - update the SPEC-036 "Report Bug" cross-ref Also drop the "roughly doubling per-chunk inference" aside from SPEC-036's background — the stream-bench A/B (min-detect 10 vs 9999) showed per-chunk re-detect is free (WER + RTF identical), so the claim is false. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
larryxiao
added a commit
that referenced
this pull request
Jun 8, 2026
033/034 are reserved for PRs #41/#42 (ROADMAP "Pending docs PRs"). The "Becoming autonomous" field-feedback row and SPEC-037's privacy note referenced the crash-sentinel (→039) and the future consented-reporting spec (→040), so point them at the free ids: SPEC-036 / 039 / 040. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
larryxiao
added a commit
that referenced
this pull request
Jun 8, 2026
ROADMAP's "Pending docs PRs" section already reserves SPEC-033 for PR #41 (Pages analytics) and SPEC-034 for PR #42 (active-install). The crash-sentinel spec was a stray 033; move it to the next free id 039: - rename SPEC-033-crash-sentinel-bug-report.md → SPEC-039-… - update the 4 SPEC-039 code comments in OpenQuackApp.swift - update the SPEC-036 "Report Bug" cross-ref Also drop the "roughly doubling per-chunk inference" aside from SPEC-036's background — the stream-bench A/B (min-detect 10 vs 9999) showed per-chunk re-detect is free (WER + RTF identical), so the claim is false. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
larryxiao
added a commit
that referenced
this pull request
Jun 10, 2026
…utonomy reflection (#78) * docs(SPEC-037/038): agent-harness + CI eval-gate proposals; ROADMAP autonomy reflection Reflection on making the repo agent-autonomous across product / ops / GTM. - ROADMAP.md gains a "## Becoming autonomous" north-star section: what exists (the contract), the meta-gap (no committed .claude/ harness), the three unlocks, and the per-domain autonomy ceilings (product privacy-capped, ops needs signing, GTM assisted-not-autonomous). - SPEC-037 (proposal): committed .claude/ harness — six scoped subagent roles, saved workflows, cron + GitHub-event triggers, and a deny-by-default permissions model with HARD human gates at every irreversible/outward step (merge, release, public post). release-bot PREPs; the cut blocks on SPEC-025. - SPEC-038 (proposal): CI eval-gate running medium-model WER/RTF on the real corpora (today gitignored → CI smokes tiny/short only). Hosted+cached corpus fetch (no audio in git, per AGENTS hard rule); WER hard-gate, RTF same-runner soft-gate; delta reported in the PR. Design-first per AGENTS (spec PRs precede implementation). e2e/app-behaviour test and the field-feedback loop noted as siblings/follow-ups. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: point field-feedback refs at free ids (033→039, 034→040) 033/034 are reserved for PRs #41/#42 (ROADMAP "Pending docs PRs"). The "Becoming autonomous" field-feedback row and SPEC-037's privacy note referenced the crash-sentinel (→039) and the future consented-reporting spec (→040), so point them at the free ids: SPEC-036 / 039 / 040. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
larryxiao
added a commit
that referenced
this pull request
Jun 16, 2026
…77) * feat(SPEC-036): recording diagnostics, health & graceful interruption The "dictation stops mid-recording, waveform freezes, partial transcript" class of bug is intermittent and was undiagnosable: the capture tap drives the WAV write, level meter, and streaming frames from one closure, so when it stops all three freeze together — and there was no observer, no logging, and no captured-vs-wall check to notice or attribute it. This adds (SPEC-036): - OpenQuackPlatform/Diagnostics: os.Logger (recording/streaming/transcription /app) + a bounded in-memory event ring for an attachable text dump. - RecordingHealth (pure): assess(wall, captured) → .incompleteCapture when the tap stopped feeding audio mid-recording (the freeze signature). - DiagnosticsReport (pure): renders the attachable .txt (version/OS/chip, wall-vs-captured, chunks, RTF, lang, recent events). - AudioRecorder: captured-frame counter → capturedSeconds; an AVAudioEngineConfigurationChange observer that auto-stops ONLY when the engine actually stopped (gated on !isRunning, so benign route changes don't truncate long dictations); lifecycle logging. - StreamingTranscriber: per-chunk duration/decision/RTF logging — the data that confirms the SPEC-035 "slow + inaccurate" reports (per-chunk re-detect). - App: graceful auto-stop + "interrupted" notice; health check + summary on every stop; a diagnostics .txt written + revealed in Finder from "Report Bug" and "Send feedback…". Also lands the previously-uncommitted SPEC-033 crash-sentinel bug-report base (checkAndMarkCrashSentinel / offerCrashBugReport / applicationWillTerminate), which SPEC-036's bug-report enrichment hooks into — they share OpenQuackApp.swift and can't be split. SPEC-033's acceptance criteria are manual (simulated crash) and not yet verified. Build + 196 tests green (12 new, covering RecordingHealth / DiagnosticsReport / the event ring). Interruption path and the file-reveal still need manual verification on a machine that reproduces the freeze. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(SPEC-036): Settings → Stats recording-health view Surface the SPEC-036 diagnostics locally so you (and users) can self-diagnose without filing a bug. Settings → Stats gains a "Recording health" subsection, gated behind the existing showUsageStats display toggle (tracking stays always-on, local): - a session incomplete-capture count + a per-recording list (wall / captured / RTF / path / lang, warning-marked when the tap stopped early), - a compact warn/error tail from Diagnostics.shared, - a "Reveal diagnostics file" button into the existing reveal flow. AppState gains a newest-first, cap-10 `recentRecordings` ring (pushed in stopAndTranscribe); `writeDiagnosticsFileAndReveal` becomes internal so the pane reaches it via the same (NSApp.delegate as? AppDelegate) handle it already uses for usageStats. Local-only — nothing leaves the Mac. Build + 196 tests green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(SPEC-039): renumber crash-sentinel 033→039 (033 reserved for #41) ROADMAP's "Pending docs PRs" section already reserves SPEC-033 for PR #41 (Pages analytics) and SPEC-034 for PR #42 (active-install). The crash-sentinel spec was a stray 033; move it to the next free id 039: - rename SPEC-033-crash-sentinel-bug-report.md → SPEC-039-… - update the 4 SPEC-039 code comments in OpenQuackApp.swift - update the SPEC-036 "Report Bug" cross-ref Also drop the "roughly doubling per-chunk inference" aside from SPEC-036's background — the stream-bench A/B (min-detect 10 vs 9999) showed per-chunk re-detect is free (WER + RTF identical), so the claim is false. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds SPEC-033 — privacy-respecting visitor analytics for the GitHub Pages landing site at
larryxiao.github.io/openquack.Why
The Pages landing is now the canonical first-impression surface (awesome-list backlinks, DMs, newsletter pitches all point there). We have zero visibility into who lands there or which sections they read. GitHub Insights covers the repo views but not the Pages site.
What's specified
_config.ymlflag + FAQ disclosure line in README + docs/index.mdPrivacy framing
The app's no-telemetry promise (about the binary) is unchanged. The Pages site is HTML served by GitHub; visiting any web page involves standard HTTP telemetry. GoatCounter aggregates and discards before persistence. The FAQ entry makes this transparent.
Test plan
🤖 Generated with Claude Code