jonah-fleet 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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)
+
+
+### Features
+
+* **autowork:** add opportunistic operational log sweep (idle GC) to Step 9 ([#285](https://github.com/juliendurandeu/jonah-fleet/issues/285)) ([8e4cf12](https://github.com/juliendurandeu/jonah-fleet/commit/8e4cf122cb949bdc23bdc3eaa1f80e4a7739dde6))
+
 ## [1.18.0](https://github.com/juliendurandeu/jonah-fleet/compare/v1.17.0...v1.18.0) (2026-09-20)
 
 
@@ -30,6 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * **prompts:** add Prior Failure Ingestion Protocol to `autowork.md` and `peer-review.md`, inspecting past open failed routine issues to extract error logs and crash milestones before implementation or review.
 * **prompts:** add resolution-triggered auto-closure to `autowork.md` and `peer-review.md`, automatically commenting on and closing past failed routine issues for a target once work is marked ready or merged.
 * **housekeeping:** expand `issues-housekeeping.md` to sweep and close stale untargeted `status:failure` routine issues older than 48 hours or whose targets are resolved, eliminating backlog clutter.
+* **autowork:** add opportunistic operational log sweep (idle GC) to Step 9 in `autowork.md`, cleaning up stale untargeted failures when the issue backlog is clear.
 
 ## [1.16.0](https://github.com/juliendurandeu/jonah-fleet/compare/v1.15.1...v1.16.0) (2026-09-19)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jonah-fleet",
-  "version": "1.18.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/ORCHESTRATION.md

@@ -168,7 +168,9 @@ Single source of truth for handling routine run failures, context extraction, an
    ```
    (or `PR #<PR_NUMBER>`). If prior failed runs exist, the runner extracts error messages, failing test names, or crash milestones from the Interruption Card and incorporates this context into Milestone 1 and its reproduction strategy, preventing repeated identical failures.
 3. **Resolution-Triggered Auto-Closure**: When a target issue or PR reaches terminal completion (a ready PR opened, review decision executed, or PR merged), the routine iterates through any open past failed routine issues for that target, posts a resolution comment referencing the successful run (including the Antigravity run footer), and closes them via `gh issue close <ISSUE> --reason completed`.
-4. **Housekeeping Garbage Collection for Untargeted Crashes**: Routine runs that fail before claiming a target (e.g. runner VM startup errors, GitHub CLI auth failures) or whose target has already been resolved are audited by `issues-housekeeping.md` and closed once older than 48 hours, keeping consumer issue lists clean and noise-free.
+4. **Garbage Collection for Untargeted / Stale Crashes (Housekeeping & Idle Autowork)**: Routine runs that fail before claiming a target (e.g. runner VM startup errors, GitHub CLI auth failures) or whose target has already been resolved are audited and closed once older than 48 hours by:
+   - `issues-housekeeping.md` during scheduled backlog maintenance sweeps.
+   - `autowork.md` Step 9 as an opportunistic idle sweep when no eligible unclaimed work exists, ensuring repositories running minimal presets without dedicated housekeeping crons stay pristine.
 
 ---
 

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.
@@ -165,8 +166,19 @@ _Generated by [Antigravity](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/ru
    - **Dual Execution Priority Routing**:
      - If running in **Cloud Actions** (`$GITHUB_ACTIONS` / `$CI`): Scan mode selects `priority/P0` or `priority/P1` issues first. Lower-priority `priority/P2` or `priority/P3` issues are eligible in cloud Scan mode ONLY if the issue has remained unclaimed for more than 48 hours (`created_at` older than 48h, acting as a cloud catchup sweep).
      - If running in **Local Agent** (`$LOCAL_AGENT`): Scan mode selects across all priorities (P0 → P1 → P2 → P3) without time gating, prioritizing active local backlog consumption.
-   - Skip assigned issues (unless stale claim per `ORCHESTRATION.md`), issues with open PRs, issues with unclosed blocking dependencies (`Blocked by #N` / `Depends on #N`), issues labeled `needs-human`, `needs-design`, or `needs-info`, and issues under cross-run cooldown.
-9. If no eligible candidate exists, STOP — run is SUCCESS with "No unclaimed work available".
+9. If no eligible candidate exists:
+   - **Opportunistic Operational Log Sweep (Idle GC)**: Before concluding an idle run, perform a lightweight sweep of open `routine-log` issues to prevent operational clutter from accumulating across repositories (especially those running minimal presets without dedicated housekeeping crons):
+     ```bash
+     STALE_FAILURES=$(gh issue list --label routine-log,status:failure --state open --limit 20 --json number,title,body,createdAt || true)
+     ```
+     For each stale failure issue:
+     - Check if it is untargeted (no `(Issue #N)` or `(PR #M)` in title/body) and older than 48 hours, OR if its referenced target issue or PR is already closed or merged.
+     - If eligible, close it with a resolution note:
+       ```bash
+       gh issue comment "$stale_num" --body "Closed by autowork idle sweep: routine failure superseded or untargeted crash older than 48 hours.\n\n_Generated by [Antigravity](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID:-})_" || true
+       gh issue close "$stale_num" --reason completed || true
+       ```
+   - STOP — run is SUCCESS with "No unclaimed work available; swept stale operational logs".
 10. If the candidate should be closed already (work done, merged PR found in git history or via `gh pr list --state merged --search "<ISSUE_NUMBER>"`), close it immediately (`gh issue close <ISSUE_NUMBER> --comment "Closed: work already merged in PR #<PR_NUMBER>.\n\n_Generated by [Antigravity](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID:-})_"`), close any lingering past failed routine run issues (`PAST_FAILURES=$(gh issue list --label routine-log --search "Issue #<ISSUE_NUMBER>" --state open --json number --jq '.[].number' || true); for p in $PAST_FAILURES; do if [ -n "$p" ] && [ "$p" != "$ROUTINE_ISSUE_NUMBER" ]; then gh issue comment "$p" --body "Resolved: work already merged in PR #<PR_NUMBER>.\n\n_Generated by [Antigravity](${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID:-})_" || true; gh issue close "$p" --reason completed || true; fi; done`), and return to step 8.
     10a. **Stale-claim reclamation:** If candidate is a stale claim per `ORCHESTRATION.md`, re-read immediately before writing, unassign the dead owner, post reclamation comment, and proceed to claim.
 11. **Claim protocol:**
@@ -209,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.