release: 0.0.3 (artisan ^0.0.6, telescope_clear fix, oldest-first MCP descriptions)#14
Conversation
…dopt oldest-first wire shape
Two long-standing doc-vs-impl gaps surfaced during the 0.0.3 release smoke test.
telescope_clear: the MCP descriptor and the CLI command's one-line
description both claimed it wiped three ring buffers (http, logs,
exceptions). The implementation has always wiped all 9 buffers
atomically (per SKILL.md Core Law 6 and lib/src/extensions/ext_clear.dart).
Rewrote both strings to enumerate the actual 9 buffers (http, logs,
exceptions, events, gates, dumps, queries, caches, magic models),
document the {"cleared": true} envelope, and make the upstream-sink
isolation (Sentry, Bugsnag still receive captured signals) explicit.
Order of records: seven of the eight read-tool descriptors claimed
'Returns newest-first' while TelescopeStore reads the queue in
insertion order (oldest at index 0, newest last) and SKILL.md Law 5
already labelled the gap as 'presenter shorthand'. The shorthand is
retired: every telescope_* description now states 'Returned oldest-
first (last entry is newest)', and Law 5 is updated to drop the
disclaimer.
No wire behavior change. Wire shape was already correct; this is a
descriptor-string fix on the agent surface.
…ot / README / doc Bumps every stale version pin in the doc surface so the published 0.0.3 artifact's documentation matches what consumers actually resolve. - CLAUDE.md + .github/copilot-instructions.md: 'fluttersdk_artisan ^0.0.2' (two spots each: Stack paragraph and Production-deps line) -> '^0.0.6'. - README.md: pinned-install snippet 'fluttersdk_telescope: ^0.0.2' -> '^0.0.3'. - doc/getting-started/installation.md: '^0.0.1' -> '^0.0.3'. - doc/getting-started/quickstart.md: 'fluttersdk_telescope ^0.0.1' -> '^0.0.3'. - doc/mcp/setup.md: '^0.0.1' -> '^0.0.3'. CLAUDE.local.md (untracked / gitignored) was updated separately in the working tree.
Bumps the example app's pinned constraint from 0.0.2 to 0.0.3 so the in-tree example resolves with the bumped path dep and the lockfile reflects fluttersdk_artisan 0.0.6 (matching telescope's own dev resolution after the constraint bump in pubspec.yaml).
… descriptions) Bumps fluttersdk_telescope to 0.0.3 and locks in the matching changes needed for publish. pubspec.yaml: - version: 0.0.2 -> 0.0.3. - fluttersdk_artisan: ^0.0.4 -> ^0.0.6. Consumers were already resolving 0.0.6 transitively (because telescope:install appends 'fluttersdk_artisan: any' to the consumer pubspec on bootstrap); telescope's own dev resolution now tracks the same version so flutter test, dart format, dart analyze, and dart pub publish --dry-run run against the artisan that consumers execute. Picks up the artisan 0.0.5 + 0.0.6 fixes: _plugins.g.dart AOT staleness detection, MCP serverInfo.version sync to 0.0.6, atomic .mcp.json writes via .tmp + rename, the mcp:install --invocation plugin-aware fallback, and the dusk_evaluate VM-routed fix. CHANGELOG.md: - Promote [Unreleased] to [0.0.3] - 2026-05-28. - New Added bullet documenting the GitHub Flow adoption (Golden Rule 7 + Branching section + delete_branch_on_merge: true). - New Changed bullet for the artisan constraint bump and what 0.0.5 + 0.0.6 fixes consumers now get for free. - New Changed bullet for the 'Returns newest-first' -> 'oldest-first (last entry is newest)' wire-shape correction. - New Fixed bullet for telescope_clear's 3 -> 9 buffers descriptor correction. - The previously accumulated Added/Changed/Fixed bullets (community CTA section, mcp:install fallback, telescope:install dropping the bin/fsa hard dependency, collectMcpTools forcing) are now part of the dated 0.0.3 entry instead of [Unreleased]. Tag flow per CLAUDE.md: merge this PR, then 'git tag 0.0.3 && git push origin 0.0.3' fires .github/workflows/publish.yml to push to pub.dev.
There was a problem hiding this comment.
Pull request overview
This PR prepares the fluttersdk_telescope 0.0.3 release by bumping the package/artisan versions, correcting MCP descriptor wording, and refreshing related docs and example metadata.
Changes:
- Bumps
fluttersdk_telescopeto 0.0.3 andfluttersdk_artisanto^0.0.6. - Updates MCP and CLI descriptions to reflect all 9 cleared buffers and oldest-first read ordering.
- Refreshes README, docs, skill guidance, changelog, and example lock metadata for the release.
Reviewed changes
Copilot reviewed 12 out of 13 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
skills/fluttersdk-telescope/SKILL.md |
Updates skill guidance to document oldest-first MCP wire ordering directly. |
README.md |
Updates the dependency snippet to ^0.0.3. |
pubspec.yaml |
Bumps package version and artisan dependency constraint. |
lib/src/telescope_artisan_provider.dart |
Updates MCP tool descriptions for clear behavior and oldest-first ordering. |
lib/src/commands/telescope_clear_command.dart |
Updates the CLI clear command description to mention all 9 buffers. |
example/pubspec.yaml |
Updates the example package version metadata. |
example/pubspec.lock |
Refreshes resolved artisan and telescope versions. |
doc/mcp/setup.md |
Updates installation docs to ^0.0.3. |
doc/getting-started/quickstart.md |
Updates quickstart package version text. |
doc/getting-started/installation.md |
Updates installation dependency snippet. |
CLAUDE.md |
Updates artisan dependency guidance to ^0.0.6. |
.github/copilot-instructions.md |
Updates Copilot guidance to match the artisan dependency bump. |
CHANGELOG.md |
Promotes release notes for 0.0.3 and documents the release changes. |
| '- Pass `level: "<name>"` (e.g. `"WARNING"`, `"SEVERE"`) to ' | ||
| 'filter by minimum log level; omit for all levels.\n' | ||
| '- Returns newest-first; pair with telescope_clear before a ' | ||
| '- Returned oldest-first (last entry is newest); pair with telescope_clearbefore a ' |
There was a problem hiding this comment.
Fixed in 09d6012. Restored the trailing space inside the string fragment ('telescope_clear before ' / 'telescope_clear to ') so the implicit Dart string concatenation renders the inter-word space. Live MCP tools/list probe confirms the corrected wording.
| '- Pass `limit: <n>` to cap the response size; default ' | ||
| 'returns the whole buffer.\n' | ||
| '- Returns newest-first; pair with telescope_clear to ' | ||
| '- Returned oldest-first (last entry is newest); pair with telescope_clearto ' |
There was a problem hiding this comment.
Fixed in 09d6012. Restored the trailing space inside the string fragment ('telescope_clear before ' / 'telescope_clear to ') so the implicit Dart string concatenation renders the inter-word space. Live MCP tools/list probe confirms the corrected wording.
| '(default returns the whole buffer; cap is ring-buffer ' | ||
| 'size).\n' | ||
| '- Returns newest-first; pair with telescope_clear before a ' | ||
| '- Returned oldest-first (last entry is newest); pair with telescope_clearbefore a ' |
There was a problem hiding this comment.
Fixed in 09d6012. Restored the trailing space inside the string fragment ('telescope_clear before ' / 'telescope_clear to ') so the implicit Dart string concatenation renders the inter-word space. Live MCP tools/list probe confirms the corrected wording.
| '- Pass `limit: <n>` to cap how many records come back ' | ||
| '(default returns the whole buffer).\n' | ||
| '- Returns newest-first; pair with telescope_clear before ' | ||
| '- Returned oldest-first (last entry is newest); pair with telescope_clearbefore ' |
There was a problem hiding this comment.
Fixed in 09d6012. Restored the trailing space inside the string fragment ('telescope_clear before ' / 'telescope_clear to ') so the implicit Dart string concatenation renders the inter-word space. Live MCP tools/list probe confirms the corrected wording.
| '- Pass `limit: <n>` to cap how many records come back ' | ||
| '(default returns the whole buffer).\n' | ||
| '- Returns newest-first; pair with telescope_clear before ' | ||
| '- Returned oldest-first (last entry is newest); pair with telescope_clearbefore ' |
There was a problem hiding this comment.
Fixed in 09d6012. Restored the trailing space inside the string fragment ('telescope_clear before ' / 'telescope_clear to ') so the implicit Dart string concatenation renders the inter-word space. Live MCP tools/list probe confirms the corrected wording.
| '- Pass `limit: <n>` to cap how many records come back ' | ||
| '(default returns the whole buffer).\n' | ||
| '- Returns newest-first; pair with telescope_clear before ' | ||
| '- Returned oldest-first (last entry is newest); pair with telescope_clearbefore ' |
There was a problem hiding this comment.
Fixed in 09d6012. Restored the trailing space inside the string fragment ('telescope_clear before ' / 'telescope_clear to ') so the implicit Dart string concatenation renders the inter-word space. Live MCP tools/list probe confirms the corrected wording.
| '- Pass `limit: <n>` to cap how many records come back ' | ||
| '(default returns the whole buffer).\n' | ||
| '- Returns newest-first; pair with telescope_clear before ' | ||
| '- Returned oldest-first (last entry is newest); pair with telescope_clearbefore ' |
There was a problem hiding this comment.
Fixed in 09d6012. Restored the trailing space inside the string fragment ('telescope_clear before ' / 'telescope_clear to ') so the implicit Dart string concatenation renders the inter-word space. Live MCP tools/list probe confirms the corrected wording.
The earlier replace_all pass to shorten 'Returned oldest-first...' lines ate the trailing space after 'telescope_clear', so the implicit Dart string concatenation produced 'telescope_clearbefore' and 'telescope_clearto' on every read tool's MCP description (7 places). Copilot review on #14 flagged each occurrence. Restored the trailing space inside each fragment ('telescope_clear before ' and 'telescope_clear to ') so the rendered descriptions read 'telescope_clear before a repro to ...' and 'telescope_clear to isolate ...' as intended. Live MCP probe confirms the corrected spacing; tests, format, analyze stay green.
Summary
Cuts
fluttersdk_telescope0.0.3 with the newfluttersdk_artisan ^0.0.6constraint, thetelescope_cleardescriptor correction, the wire-shape alignment in everytelescope_*MCP description, and the doc-surface refresh.Why now
fluttersdk_artisanreleased 0.0.5 + 0.0.6 on 2026-05-23 / 2026-05-28. Consumers were already pulling 0.0.6 transitively (the post-installfluttersdk_artisan: anyline thattelescope:installappends to a consumer's pubspec lifts the constraint), but telescope's own dev resolution was pinned to 0.0.4 via^0.0.4(Dart pre-1.0 caret =>=0.0.4 <0.0.5). The mismatch meant the published artifact's tests, format, anddart pub publish --dry-runran against an older artisan than consumers see. This release closes the gap.Smoke test (pre-release, /tmp consumer)
Scaffolded a fresh
flutter createapp at/tmp/telescope_smoketest, wiredfluttersdk_telescopeas a path dep, then exercised the full bootstrap:dart run fluttersdk_telescope telescope:installfinishes end-to-end (bin/dispatcher.dart, lib/app/_plugins.g.dart, lib/app/commands/_index.g.dart scaffolded; bin/fsa AOT compiled; plugin:install registers; lib/main.dart injected with the kDebugMode-gated TelescopePlugin.install() + ExceptionWatcher + DumpWatcher).fluttersdk_telescope0.0.3 (path),fluttersdk_artisan0.0.6 (transitive)../bin/fsa listshows 28 commands; the 6telescope:*are present;telescope:clearone-liner now reads 'Clear all 9 telescope ring buffers atomically (...)'../bin/fsa mcp:serve+ JSON-RPCinitialize+tools/list): 19 tools (9telescope_*+ 10artisan_*), serverInfo.version 0.0.6.telescope_cleardescription now enumerates the 9 buffers;telescope_taildescription now says 'oldest-first (last entry is newest)' instead of 'newest-first'.Verification
dart format lib/ test/ bin/: zero diff.dart analyze lib/ test/ bin/: zero issues.flutter test --exclude-tags=integration --timeout=30s: 253 / 253 green.dart pub publish --dry-run: only the expected 'files modified in git' warning, archive 95 KB.Changes (4 commits)
fix(mcp+cli): correct telescope_clear descriptor (3 -> 9 buffers) + adopt oldest-first wire shape—lib/src/telescope_artisan_provider.dart,lib/src/commands/telescope_clear_command.dart,skills/fluttersdk-telescope/SKILL.md.docs: refresh artisan ^0.0.6 + telescope ^0.0.3 across CLAUDE / copilot / README / doc— CLAUDE.md, .github/copilot-instructions.md, README.md, doc/getting-started/installation.md, doc/getting-started/quickstart.md, doc/mcp/setup.md.chore(example): pin fluttersdk_telescope to 0.0.3 + refresh lockfile— example/pubspec.yaml, example/pubspec.lock.release: 0.0.3 ...— pubspec.yaml (version + artisan constraint), CHANGELOG.md (promote [Unreleased] -> [0.0.3] 2026-05-28).Post-merge tag flow
Per
CLAUDE.mdBranching section, after this PR squash-merges:.github/workflows/publish.ymlfires on the tag and pushes 0.0.3 to pub.dev.