jonah-fleet 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to `jonah-fleet` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.20.0](https://github.com/juliendurandeu/jonah-fleet/compare/v1.19.0...v1.20.0) (2026-09-20)
+
+
+### Features
+
+* **orchestration:** introduce question-driven telemetry guardrails and 3-tier measurement taxonomy ([#293](https://github.com/juliendurandeu/jonah-fleet/issues/293)) ([23cd994](https://github.com/juliendurandeu/jonah-fleet/commit/23cd994c7e928e2d57b785965a507e115cda1cc7))
+
 ## [1.19.0](https://github.com/juliendurandeu/jonah-fleet/compare/v1.18.0...v1.19.0) (2026-09-20)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jonah-fleet",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Standalone autonomous agent fleet with Symphony orchestration, claim protocols, and continuous improvement loops",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/docs/AGENTS.template.md

@@ -47,6 +47,15 @@ tests/            # Test suites
 - **Zero-Guesswork Ambiguity Gate**: Never make silent assumptions about underspecified requirements, schemas, edge cases, or UX flows. Stop and ask clarifying questions before implementation.
 - **Structured Clarifications & Grilling**: When asking questions, propose 1–2 high-leverage questions at a time with concrete options or trade-offs. For complex features or fuzzy requirements, invoke `/grill-me` to stress-test the design before writing code.
 
+## Telemetry & Measurement Intent
+
+- **Question-First Principle**: Every custom analytics event must answer an explicit question that influences a product, architectural, or growth decision. If observing an event would never change what is built, prioritized, or retired, do NOT instrument it.
+- **3-Tier Telemetry Taxonomy**:
+  - **Tier 1 (Core Funnel & Growth Levers)**: Acquisition, activation, retention, referral, revenue (North Star metrics). Instrumentation is **mandatory and rigorous**: must include impression denominator (`_shown`), interaction CTA (`_clicked`), outcome/completion (`_completed`), and structured failure/abandonment branches (`_failed` with `reason`). Must pair with a companion `Measure: ...` tracking issue.
+  - **Tier 2 (Exploratory Product UX & Feature Flags)**: Secondary features and discovery surfaces. Instrument only when tied to an explicit hypothesis or UX discovery question in the issue specification.
+  - **Tier 3 (Passive Chrome & Utility / Easter Eggs)**: Cosmetic toggles, credits popovers, dismiss buttons, informational tooltips. **Explicitly exempt from custom events**; rely on autocapture, web vitals, or session replay if diagnostic data is ever needed.
+- **Zero Vanity Tracking Guardrail**: Never emit telemetry purely for checklist compliance. Avoid adding arbitrary click trackers to passive or cosmetic UI surfaces.
+
 ## Conventions
 
 - **Language**: All code, comments, commit messages, and PR titles must be written in **English**.

package/templates/prompts/autowork.md

@@ -104,6 +104,7 @@ a. **Read the target issue and check eligibility.** Eligible = open, unassigned
    - **Automated review passes**: run `/code-review` (evaluating along Standards in `AGENTS.md` and Spec in the issue's `## Tasks`) and security review over the diff. Fix what they flag.
    - **Repository conventions scan**: read and verify all rules and conventions specified in `AGENTS.md` (or `CLAUDE.md`/`GEMINI.md`), project-level skills in `.agents/skills/`, and project documentation.
    - **Design System & Viewport Pre-flight** (for frontend/UI diffs): self-audit diffs against design tokens (no arbitrary class overrides), WCAG AA 4.5:1 contrast ratios on dark/light surfaces, single primary CTA hierarchy per screen, and mobile viewport crowding (avoid stacked nudges/banners above the fold at ~390px).
+   - **Telemetry Contract Audit**: verify that any new interactive surfaces adhere to the 3-Tier Telemetry Taxonomy in `AGENTS.md`: Tier 1/2 flows must have question-backed events with impression denominators (`_shown`) and documented properties in the event catalog (`ARCHITECTURE.md`), while Tier 3 utility/cosmetic surfaces must be explicitly exempt with zero vanity click-trackers.
    - **Documentation accuracy**: update relevant docs (`ARCHITECTURE.md`, `CODEMAP.md`, `API.md`, `CHANGELOG.md` if maintained by repo).
    - **Build & type-check verification**: run the repository's test, type-check, and lint commands from `AGENTS.md` (e.g. `npm test`, `npm run type-check`, `npm run lint`, `pytest`, `cargo test`). Confirm zero errors and zero test failures.
    - **Active Origin Sync & Clean-Merge Gate**: Run `git fetch origin main && git merge origin/main --no-edit` to absorb any newly merged pull requests and resolve any conflicts locally. Verify `git merge-tree origin/main HEAD` reports no conflicts before marking ready.
@@ -220,6 +221,10 @@ _Generated by [Antigravity](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/ru
       - Apply the `needs-info` label and release the claim (unassign).
       - Select the next candidate (evaluating ambiguous issues counts toward step 12's infeasible-continuation cap).
     - **Intent vs. Defect Guardrail**: When investigating issues related to low conversion, zero-click events, or underperforming features: verify whether the issue is a software defect or a lack of user intent. If data indicates the root cause is **lack of user intent** (e.g. button is rendered above fold and functions correctly when clicked, but user interaction rate is <2%) rather than a software defect, do NOT fall into the **telemetry rabbit hole** (adding elaborate fallback telemetry, downstream error handling, or defensive rendering). Categorize the issue as a **product/UX question** (`needs-design` / `roadmap/*`), comment explaining the lack of user intent, release the claim (unassign), and select the next candidate.
+    - **Telemetry Design & Measurement Contract Gate**: When implementing new features or interactive surfaces, classify them according to the 3-Tier Telemetry Taxonomy in `AGENTS.md`:
+      - **Tier 1 (Core Funnel & Levers)**: You MUST implement the complete measurement contract: impression denominator (`_shown`), interaction CTA (`_clicked`), completion (`_completed`), and structured failure/abandonment branches (`_failed` with `reason`). Update the repository's custom events catalog (`ARCHITECTURE.md` / `DATA_CONTEXT.md`).
+      - **Tier 2 (Exploratory UX)**: Instrument only if the issue specification explicitly defines a hypothesis, metric question, or companion `Measure: ...` issue.
+      - **Tier 3 (Passive Chrome & Utility / Easter Eggs)**: Do NOT add custom events or click trackers for cosmetic easter eggs, footer attribution popovers, theme toggles, or standard modal dismissals. Keep the codebase free from vanity tracking noise.
     - If infeasible: comment explaining blocker, release claim (unassign), and select next candidate (up to 3 infeasible evaluations per run). If permanent blocker on 2nd strike, post the mandatory 4-part escalation card (`## 🛑 Escalation: Human Decision Required`), apply `needs-human` label, and tag repo owner.
       12a. **Umbrella-issue handoff + batching:** If candidate is an umbrella epic:
     - Read `🧭 Decomposition plan` comment (or create if first run).

package/templates/prompts/peer-review.md

@@ -131,8 +131,11 @@ Check if `$PR_NUMBER` is set:
    - **WCAG AA Contrast**: Enforce minimum 4.5:1 contrast on readable text (e.g. `text-gray-400` minimum on dark surfaces; avoid muted unreadable text).
    - **CTA Hierarchy**: Verify at most one primary forward CTA (`.btn-primary`) per active screen/tab.
    - **Mobile Viewport Budget**: Verify that new banners, nudges, or sticky elements do not stack concurrently above the fold on mobile viewports (~390px).
-4. If PR modifies rendered UI, verify screenshots or visual components if tooling/scripts are available.
-5. Run repository verification commands (tests, type-check) ONLY if CI status is unconfirmed or failing. If remote CI (such as GitHub Actions or Vercel preview) is already green and passing on the head commit, treat CI as verified. If verification commands must be run locally, specify `WaitMsBeforeAsync: 10000` and NEVER call `schedule` or yield the turn with plain text while waiting for background tasks.
+4. **Telemetry & Measurement Contract Pass**:
+   - **Question-First Validation**: Verify that any new custom analytics events answer a clear, decision-driving question per the 3-Tier Taxonomy in `AGENTS.md`. Flag vanity click-trackers on Tier 3 passive chrome/easter eggs as non-blocking cleanup (recommend removal).
+   - **Funnel Completeness**: For new Tier 1 user funnels or critical workflows, verify the telemetry contract: impression denominator (`_shown`), interaction (`_clicked`), and failure states (`_failed` with `reason`) are captured, and events are documented in the custom events catalog (`ARCHITECTURE.md` / `DATA_CONTEXT.md`). Flag missing denominators on core funnels as blocking.
+5. If PR modifies rendered UI, verify screenshots or visual components if tooling/scripts are available.
+6. Run repository verification commands (tests, type-check) ONLY if CI status is unconfirmed or failing. If remote CI (such as GitHub Actions or Vercel preview) is already green and passing on the head commit, treat CI as verified. If verification commands must be run locally, specify `WaitMsBeforeAsync: 10000` and NEVER call `schedule` or yield the turn with plain text while waiting for background tasks.
 
 ### Step 5: Classify Findings & Make Decision
 

package/templates/skills/to-spec/SKILL.md

@@ -64,6 +64,19 @@ A list of testing decisions that were made. Include:
 - Which modules will be tested
 - Prior art for the tests (i.e. similar types of tests in the codebase)
 
+## Telemetry & Measurement Decisions
+
+A list of measurement decisions for this feature based on the 3-Tier Telemetry Taxonomy:
+
+- **Tier Classification**: State whether this surface is Tier 1 (Core Funnel & Growth Levers), Tier 2 (Exploratory Product UX), or Tier 3 (Passive Chrome & Utility / Easter Eggs).
+- **If Tier 1 or Tier 2**:
+  - **Question this answers**: What concrete product, growth, or UX decision will this data influence?
+  - **Metric & Denominator**: What is the impression denominator (e.g. `_shown`) and target metric defining success or failure?
+  - **Events & Properties**: Required event names (`snake_case`), triggers, key properties, and structured failure/abandonment states (`reason`).
+  - **Measurement issue**: Outline the companion `Measure: ...` tracking issue to be filed upon merge.
+- **If Tier 3**:
+  - Explicitly declare: `Telemetry: None (Tier 3 utility/cosmetic — no decision value).` Do NOT add vanity click trackers.
+
 ## Out of Scope
 
 A description of the things that are out of scope for this spec.