@hecer/yoke 1.13.0 → 1.15.0

package/docs/DASHBOARD-EVOLUTION.md

@@ -1,6 +1,6 @@
 # Dashboard evolution
 
-The local dashboard is an actionable workspace for registered Yoke projects. It reads the same saved project, loop, goal, acceptance, and measurement data as the CLI. Project-controlled text is rendered through `textContent`, and the server remains bound to the loopback interface with same-origin authorization for pause requests.
+The local dashboard is an actionable control room for registered Yoke projects. It reads the same saved project, loop, goal, acceptance, and measurement data as the CLI. Project-controlled text is rendered through `textContent`, and the server remains bound to the loopback interface with same-origin session authorization for typed controls. The full feature contract is in [DASHBOARD-OVERHAUL.md](DASHBOARD-OVERHAUL.md).
 
 ## Overview
 
@@ -10,14 +10,28 @@ Cards also show the reported current task and saved blocker reason when availabl
 
 An active loop report more than 20 minutes old is labeled **unconfirmed**. This means Yoke has an old active report, not evidence that the process is still live. The overview can be searched by project name, canonical path, or goal objective and filtered to All, Active, or Needs attention. A no-match state explains the result and provides a clear action that resets both search and filter.
 
+## Workspace control room
+
+The overview ranks projects by attention, last activity, recorded tokens, reported cost, accepted work, or name. Search and status filters compose with the ranking, and the validated URL hash preserves the selected screen and time scope. A project row opens the live view without losing the operator’s navigation context.
+
+The project live view shows goal and loop state independently, freshness, current worker metadata, objective progress, last successful sync, pause/resume actions at the existing safe boundary, an operator-note form, a queued-change form, and a bounded expandable event timeline. Notes are append-only events. Changes become pending inbox requests and are consumed by the existing planning boundary; the browser cannot run arbitrary commands.
+
+## Measurement coverage
+
+The dashboard labels recorded, partial, unknown, stale, corrupt, unavailable, and empty data separately. **Measurement coverage** is always shown alongside analytics: missing provider usage or price is not reconstructed, and a missing bucket means no recorded activity rather than a measured zero. A stale active report is shown as unconfirmed, not healthy.
+
 ## Durable navigation
 
-The URL hash stores the current screen, project, project tab, period, UTC grouping, and complete custom date range. Supported screens are the overview, workspace comparison, and project detail. Supported project tabs are Now, Usage & time, and Results; periods are 1, 7, 30, 90, or 365 days; groupings are day, week, or month. Custom dates must be real ISO calendar dates in chronological order and cover at most 366 inclusive days.
+The URL hash stores the current screen, project, project tab, period, UTC grouping, ranking/filter state, and complete custom date range. Supported screens are the overview, workspace analytics, and project detail. Supported project tabs are Now, Usage & time, Results, and History; periods are 1, 7, 30, 90, or 365 days; groupings are day, week, or month. Custom dates must be real ISO calendar dates in chronological order and cover at most 366 inclusive days.
 
 Invalid hash state returns to the overview with the 30-day/day defaults. Browser back and forward, a page reload, and Refresh restore the validated state. Refresh reloads data without resetting the selected view or controls. Starting any navigation aborts earlier fetches and changes a request generation, so an older response cannot replace the current screen.
 
 The workspace comparison schedules at most three project analytics requests at once. If navigation changes, in-flight fetches are aborted and no additional obsolete project requests are scheduled. All projects and individual project links remain available in the navigation while viewing the comparison.
 
+## Analytics and history
+
+Workspace and project analytics expose time-bucketed recorded tokens, calls, duration, outcomes, cost state, and rankings by agent, provider, model, variant, role, phase, project, and run. The history explorer exposes at most 100 events in chronological order and identifies run, story, phase, agent/provider/model metadata, local time, and UTC time when recorded. Unknown values remain unknown; no chart or comparison converts missing measurements to zero.
+
 ## Usage comparisons
 
 Usage & time compares the selected period with the immediately preceding period of exactly the same duration. A single time boundary is captured before either analytics request is made. The comparison covers recorded input plus output tokens, recorded acceptance events, and reported cost.

package/docs/DASHBOARD-OVERHAUL.md

@@ -0,0 +1,146 @@
+# Dashboard Overhaul: Feature Contract
+
+Status: approved implementation scope
+Date: 2026-09-08
+
+This document turns the dashboard request into executable product definitions.
+Each feature below has a bounded behavior, source of truth, safety rule, and
+acceptance proof. It is an implementation contract, not a list of future ideas.
+
+## North star
+
+Yoke Dashboard is a local-first operations console for autonomous work. A user
+can move from workspace-level ranking to one run, understand what happened,
+intervene safely at a loop boundary, and leave a durable note or change request
+without interrupting the worker or inventing a second execution path.
+
+## Feature definitions
+
+### F1 — Unified workspace control room
+
+The overview loads all registered projects into one ranked workspace. Each row
+shows project identity, current state, freshness, objective, last activity,
+latest run, token totals, cost coverage, accepted/failed outcome, and the next
+available safe action. A project can be sorted by attention, active state, last
+activity, token usage, cost, acceptance, or name. Search and status filters are
+composable and persist in navigation state.
+
+Source: registry, goal/loop snapshots, events, history measurements, and checks.
+
+Rule: missing projects and partial telemetry remain visible; an unknown metric
+never becomes zero.
+
+### F2 — Historical telemetry and rankings
+
+The dashboard exposes a selectable date range and bucket (day, week, month) for
+workspace and project views. It aggregates input, output, cached, cache-write,
+reasoning, total tokens, measured/unknown calls, attempts, accepted runs,
+repairs, escalations, elapsed time, and reported cost. It ranks projects,
+agents, providers, models, roles, phases, and runs, with measurement coverage
+shown alongside every aggregate.
+
+Source: durable history archives plus bounded live events.
+
+Rule: aggregation is deterministic and bounded; corrupt archives are reported
+as coverage gaps, not silently discarded or counted as zero.
+
+### F3 — Run explorer and event timeline
+
+A project detail view provides a run list and a chronological timeline. Users can
+expand an event to inspect run/attempt/story/phase identifiers, agent metadata,
+token fields, outcome, and source timestamp. The view supports the same date
+range and an explicit “live” scope.
+
+Source: event stream and history records, joined by run ID where available.
+
+Rule: show UTC and local time clearly; bound event and archive reads; stale live
+data is labeled unconfirmed.
+
+### F4 — Safe live controls
+
+The selected project has pause and resume controls. Pause uses Yoke’s existing
+`.yoke/loop.pause` and `.yoke/goal.pause` safe-boundary mechanisms. Resume calls
+the existing loop/goal runner with one guarded invocation and respects the loop
+lock; it never starts a duplicate worker. The UI reports requested, running,
+paused, blocked, and failed-to-start states separately.
+
+Rule: all writes require loopback same-origin plus the dashboard session token.
+No action accepts a filesystem path or shell string from the browser.
+
+### F5 — Operator notes and queued changes
+
+While work runs, a user can append a short operator note or queue a typed change
+request. Notes are append-only and displayed in the timeline. Change requests
+reuse Yoke’s existing append-only change inbox and are processed at its normal
+safe planning boundary. The UI shows pending/applied state and the request ID.
+
+Rule: notes and changes are never executed as shell commands. Input is bounded,
+validated, escaped on render, and retained as project-local operational history.
+
+### F6 — Theme, density, and responsive access
+
+Dark and light themes use the design tokens in `DESIGN.md`; first load respects
+system preference, then remembers the user’s choice. The shell works at desktop,
+tablet, and narrow widths. Tables remain scannable through column priorities,
+horizontal overflow where necessary, and accessible labels.
+
+Rule: contrast, focus, reduced motion, keyboard navigation, and non-color status
+signals are tested; visual polish cannot hide loading, empty, error, or stale
+states.
+
+### F7 — Honest operational states
+
+Every live panel shows last successful sync, source scope, and data coverage.
+Active-but-stale work becomes “unconfirmed”; unavailable costs/tokens are
+explicit. Corrupt project files produce an actionable per-project error without
+breaking the workspace view.
+
+Rule: the dashboard never claims process health merely because a status file says
+running; freshness and source errors are part of the displayed state.
+
+### F8 — Stable local API contract
+
+The server provides bounded, same-origin JSON for workspace overview, project
+snapshot, project history/events, and typed controls. Responses are safe to
+render as untrusted project text. Query ranges, limits, sort keys, and action
+payloads are schema-validated.
+
+Rule: preserve existing routes where possible, keep the server loopback-only,
+and add tests for authorization, path safety, malformed input, concurrency, and
+partial history.
+
+## Delivery slices
+
+The Yoke loop executes these slices in dependency order:
+
+1. Contract, design tokens, shared telemetry/control types, and API helpers.
+2. Historical aggregation, run/event projections, and workspace endpoints.
+3. Typed operator controls, append-only notes, and guarded resume.
+4. New shell, theme system, workspace ranking, and responsive state components.
+5. Project live view, controls, timeline, notes, and queued changes.
+6. Analytics/history explorer with all rankings and coverage explanations.
+7. Accessibility, loading/error/empty/stale states, performance bounds, and
+   focused regression tests.
+8. README/docs synchronization and final integrated verification.
+
+## Non-goals for this release
+
+- Remote multi-user access, accounts, or cloud storage.
+- Arbitrary shell execution from the browser.
+- Replacing the loop, goal runner, provider routing, or lock protocol.
+- Fabricating historical metrics that were not recorded.
+- A second real-time transport dependency; polling with freshness indicators is
+  sufficient for the local-first release.
+
+## Acceptance checklist
+
+- A workspace user can rank projects by attention, activity, tokens, cost, and
+  name and open a project without losing filters.
+- A project user can inspect a bounded historical run/event view and identify
+  agent/provider/model/role/phase/time when recorded.
+- A project user can pause at the existing safe boundary, resume without a
+  duplicate loop, add a note, and queue a change request from the UI.
+- Dark/light themes, keyboard focus, responsive layout, and reduced motion work.
+- Partial, unknown, stale, corrupt, and missing data are explicit and isolated.
+- Existing dashboard security and tests remain green; new behavior has focused
+  tests plus build/lint coverage.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Cross-agent coding harness for seven supported CLIs: curated skill canon, mechanical safety gates, autonomous loop with proof artifacts. CLI: npm i -g @hecer/yoke",
   "contextFileName": "GEMINI-EXTENSION.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hecer/yoke",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "One harness, seven agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo and Pi: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {