Tracker dashboard
A self-contained, double-clickable HTML view of .forge/tracker.yaml. Its data files
(tracker.js, signals.js, metrics.js, usage.js) and the reference graph are generated and
gitignored — ./forge-start.sh builds them once in a fresh clone, the hooks below keep them
current, and the hosted copy on Cloudflare Pages is built by .claude/lib/pages-build.sh (this
folder is the Pages build output directory; the doc site lands in docs/ beside it). Reads from
sibling files (tracker.js, signals.js, optionally metrics.js / usage.js) that mirror
project state as window.TRACKER / window.SIGNALS / window.METRICS / window.USAGE. No web
server, no build step. _headers is Cloudflare Pages configuration, not a page asset: it marks the
generated data files Cache-Control: no-cache, so a fresh deploy is visible on the next load instead
of after the edge’s week-long default TTL.
How the hosted copy gets its data. The Pages project deploys this repo without a build command
(its settings are not ours to change), so it serves only what is committed — and on main the data
files are gitignored. The Publish dashboard workflow (.github/workflows/publish-dashboard.yml) is
the build step Pages does not run: on every push to main it runs pages-build.sh, commits the
generated files on top of main and force-pushes the result to the live branch, which Cloudflare
deploys at https://live.forge-et-harness.pages.dev/. _redirects on main forwards the production
URL there, so https://forge-et-harness.pages.dev/ keeps working; the workflow drops that file on
live itself so the live site cannot redirect to itself. live is a generated artifact — nothing
merges into it and nobody commits to it. A consequence worth knowing: every other branch’s preview
deployment carries the redirect too, so a PR preview of index.html changes is not viewable; check
those locally.
Files
| File | Contents | Source | Refresh |
|---|---|---|---|
index.html |
Main dashboard — hero, KPI strip, setup gates, tabbed delivery phases, conditional team table, conditional release/UAT section, conditional wave drumbeat, signals tiles, conditional delivery-metrics section, conditional usage line, recent activity rail. | hand-edited | n/a |
usage.html |
Per-phase / per-day / per-developer / per-model token-usage breakdown. Linked from the index Usage section when local usage data exists. | hand-edited | n/a |
tracker.js |
window.TRACKER = JSON mirror of tracker.yaml. |
.forge/tracker.yaml (via yq) |
regen-tracker-dashboard.sh hook |
signals.js |
window.SIGNALS = precomputed inputs for the S6 (lessons) signal tile: the weekly cadence, the total, and how many lessons are in each sync status. The other tiles are computed in the browser from window.TRACKER. |
.forge/lessons.md |
regen-tracker-dashboard.sh hook |
metrics.js |
window.METRICS = aggregate delivery-metrics / estimation signals. |
.forge/metrics/*.jsonl |
regen-metrics-dashboard.sh hook |
usage.js |
window.USAGE = aggregated token-usage data for this project. Gitignored (per-developer-per-machine). |
~/.claude/forge-usage.jsonl (filtered by current project) |
regen-usage-dashboard.sh hook |
View
Double-click index.html. It opens in your default browser via file://. All
four data files are loaded via regular <script> tags (no fetch(), which is
blocked under file://). Missing data files are handled gracefully: tracker
absent → full-page fallback; signals absent → the Lessons tile (S6) reads as a placeholder; metrics
absent or empty → Delivery Metrics doesn’t render; usage absent → the Usage
section doesn’t render at all.
A worktree’s copy, in the Claude Code app’s browser pane. The pane’s
dashboard entry in .claude/launch.json serves the main checkout’s
dashboard. To check a change made in a worktree, add a temporary entry that runs
.claude/lib/serve-static.js <port> ../worktrees/<name>/forge-et-harness/.forge/dashboard
(a relative path), copy the gitignored data files (tracker.js, signals.js,
metrics.js, usage.js) into that worktree’s .forge/dashboard/, compare the
two side by side, then stop both servers and remove the temporary entry. A
dashboard change is checked in a browser, not only by a Node script.
Refresh
Automatic. Three hooks keep the data files in sync:
.claude/hooks/regen-tracker-dashboard.sh— onPostToolUse, regeneratestracker.jswhen.forge/tracker.yamlis edited andsignals.jswhen.forge/lessons.mdis edited; onStop, regenerates both at the end of every turn, which catches writes no Edit/Write hook sees (a worktree session, a Bash write)..claude/hooks/regen-metrics-dashboard.sh— onPostToolUse, regeneratesmetrics.jsfrom.forge/metrics/*.jsonlafter tracker edits or metrics-ledger edits. Empty ledgers producewindow.METRICS.empty = true, so the section hides..claude/hooks/regen-usage-dashboard.sh— regeneratesusage.json every Claude CodeStopevent in this project.
After Claude edits any of those source files, just refresh the browser tab.
Manual fallback for tracker.js (e.g., after a hand-edit outside Claude):
cd .forge/dashboard
{ printf 'window.TRACKER = '; yq -o=json . ../tracker.yaml; printf ';\n'; } > tracker.js
yq is already required by the harness gate-state hooks — install with
brew install yq (macOS) if needed. Without yq the hook fails open with a
one-line stderr note; tracker.js will go stale until you install it or run
the manual command.
The dashboard never edits tracker.yaml, spec/plan files, or lessons.md —
it’s a read-only view.
What the dashboard shows
Formats
Every date leads with its weekday and reads day, month, year — Thu 17 Sep 2026;
Thu 17 Sep where space is tight (the drumbeat bars stack weekday, day and month);
a due date reads Fri 20 Nov; the usage page reads Sun 2026·10·11. Relative times are spelt out (9 days ago, 7 hours ago), and
counts are plain numbers, never zero-padded. A field holding N/A shows as a
dash, the same as an empty one, except in an Owner column, where
“N/A” marks a dropped feature or slice or a won’t-fix bug, which nobody will own,
and a dash marks work nobody has picked up yet. Hovering a dropped feature or slice row,
or its drawer (“Dropped by”), and a won’t-fix bug’s drawer (“Decided by”), names who
decided (decided_by). No row is faded: a dropped
feature or slice and a won’t-fix bug show their state through the status chip and the
“N/A” owner, in normal text, as a done one does.
Hero
The project name is the header’s; the page heading repeats it for screen readers
only. Only when there is no phase row to carry it does the hero show a one-line
status string answering “where are things?” (derived from setup.* +
delivery.current_phase + delivery.phases: a setup stage before Gate 3, “Phase N
sealed · Phase N+1 not yet opened” between phases, “All phases sealed” at the end).
While a phase row is shown, its heading carries “Phase N · title” and the done count
instead. The hero no longer has a second line: the accepted risks and spikes are
listed under the Setup gates, blocked features are named in the phase row’s In
progress tile, and the update time is the header’s badge: the newest last_updated
on any tracker entry, since the tracker has no top-level timestamp.
At-a-glance
Once delivery phases exist, the top of the page reads the whole project; one row per phase (items 3 and 4) follows the Setup section, just above Delivery, in phase order. Every row has the same heading — a caret, “Phase N · title” (with the status for a phase not in progress, and ✓ on a sealed one), the meta line and, for the active phase, the pace line — and clicking the heading folds or opens the tiles and progress bar under it. On every load the phase in scope (item 3) starts open and every other phase starts folded, so when Phase 2 opens, its row opens and Phase 1’s folds, with no change to the page:
- Whole project — Setup gates, Total features (split by phase, “N in Phase 1 · M in Phase 2”), Done (with the percentage and the shipped and dropped split) and Remaining (with its percentage: everything not done or dropped, in progress included, split by phase — so Done + Remaining = Total, and their percentages add up to 100%; a feature with no known phase is named as such rather than left out).
- The project-wide overall progress bar. The tiles’ percentages are features
closed (shipped or dropped) over all features; the progress bars also weigh open
bugs. A bar’s headline is features closed ÷ (all features + the open bugs), each
open bug (open or in progress) counted as a share of a feature by severity — high
0.5, medium 0.25, low 0.1 (
BUG_WEIGHTinindex.html). A fixed or won’t-fix bug is not counted, because fixing it finished work its feature had already claimed. So open bugs hold a bar below the Done tile, fixing them moves it up, and a phase’s bar reads 100% only when every feature is closed and none of its bugs is open — the phase-seal condition. Work in flight extends the fill in a lighter shade: a feature sized by stage (FEATURE_PHASE_WEIGHT), a bug in progress at half its share. The line under the bar reads “N of M done · K in progress · B open bugs (I in progress) · Phase 1 x% · Phase 2 y%” (the phase figures weighed the same way). The weights and the sum are not on the page: hovering anywhere on the block — its heading, percentage, bar or the line under it — shows them, with their numbers, and hovering a “Phase N x%” figure shows that phase’s own sum. Before any feature exists, the bar shows the setup gates’ progress instead, and hovering it says how that is worked out. - The phase row that starts open — the active phase, or between phases the next one to open,
so Phase 2’s row opens by itself. A
current_phaseleft pointing at a sealed phase is treated as no active phase. Its heading is “Phase N · title”; under it, thedue_date, the done count with its percentage and the unresolved bugs scheduled for the phase (bugs[].delivery_phase, open or in progress — the phase cannot seal until each is fixed, closed as won’t-fix or moved). For the active phase a pace line follows: working days left to the due date (today included), the features per working day needed to close the rest (features not shipped and not dropped), and the rate so far — shipped features per working day fromstartedthrough yesterday. Dropped features are not counted in the rate: they are not delivery, and a drop is recorded in the phase where it was decided, so counting them would raise the active phase’s rate with every later-phase drop. The ✓ on pace / ⚠ behind pace verdict appears only once 15 working days have passed (PACE_MIN_DAYS), because early features are mostly foundations and sizes differ, so a short run predicts little; before that the line shows the numbers alone. A working day is a weekday that is not on the team’s holiday list,delivery.holidaysintracker.yaml. With no list, every weekday counts. Hovering over the line shows how each figure is worked out, with the numbers that went into it: features left, working days left and the due date; features shipped, working days elapsed and the start date; the dropped features left out; when the verdict appears; and the holiday list used. Then four tiles: Features (paused noted — dropped ones are shown under Done), Done, In progress (features inspec,workitem-decompose,plan,devorreview, and which of them are blocked) and Backlog (how many are ready to start — every dependency shipped — and how many are waiting). Done, In progress and Backlog each show their share of the phase’s features, so they add up to 100% (paused features aside). Done is rounded on its own, matching the phase heading; In progress and Backlog split the rest of 100 by largest remainder, so separate rounding cannot make the row read 99% or 101%. The project row’s Remaining is worked out the same way against Done. With paused features in the phase, each share is rounded on its own. Up to three blocked or ready features are named in the tile; the tooltip always lists them all. Every tile whose figure is worked out says how on hover: Done (its share, shipped and dropped) and Remaining on both rows, In progress (the blocked features) and Backlog (the ready and claimed ones). A phase card’s hover covers its mini bar and its count alike. - The phase progress bar — the same bar over the phase’s own features and the
bugs scheduled for it (
bugs[].delivery_phase): with no open bug its headline equals the phase’s Done tile, and the line under it reads “N of M done · K in progress · B open bugs (I in progress)”. Every phase row has its own, folded with the row when the row is folded. The Delivery section’s phase cards show the same figure, with the feature count and the open bugs: “50/73 · 66% · 17 open bugs”.
Blocked means started work waiting on a blocked_by dependency that is not yet
at ship or done, other than the feature’s own sub-features: a parent delivered
through its parts (F38 through F38-a … F38-h) is progressing, not blocked. A backlog
feature whose dependency has not shipped is waiting its turn in the build order, so
it is counted as waiting, not blocked. A dependency chip’s hover text uses the same
words: “Waits on F1-b” on a backlog feature, “Blocked by F1-b” on started work.
Before phases exist, or once every phase is sealed, only one row is shown: Setup
gates, Total features, Done, In progress and Not started (backlog
and paused features — the started ones are in In progress), with the progress bar
below it. A dropped feature counts as done — it
is an exit state, the same as a dropped foundation slice (.claude/rules/tracker.md:
a phase seals when every feature is done or dropped). So Done is
ship + done + dropped, the phase tabs’ N/M uses the same count, and the
progress bars give a dropped feature full weight. The Done tile’s sub-line counts
shipped and dropped separately, so a dropped feature is never read as built; its
row stays in its phase’s list with a DROPPED badge and a full meter in the done colour (tooltip “dropped”). Every value comes from tracker.yaml
alone, so the strip renders whether or not local usage data exists.
Setup
A four-dot row (PRD → Architecture → Foundation → Decomposition; “Arch” and
“Decomp” at phone widths) with labels and gate-pass dates. Foundation slices
collapse behind a disclosure headed “Foundation slices · N” (N is every slice,
dropped ones included). The list is built from the Delivery feature list’s rows, at
the same full width: Slice (“FS-1 · title”), Status, Owner (the slice’s assignee,
under the same name as the feature and bug lists’ owner column), a Progress meter
filled by status as a feature’s is by stage (not started as backlog, in progress as
development), Updated, and a caret that opens the slice’s drawer — status, owner, spec
and plan paths, started and updated dates, who dropped it (decided_by), and its
notes. Below 1080px a row wraps onto two lines, as a feature row does. When all four gates pass and foundation is done,
the section collapses to a one-line ✓ Setup complete · sealed <date>
summary under the dot row; the line is a disclosure holding one block per gate
(owner, status, date, notes, risks and spikes, and Foundation’s slice list, each
folded), so the phase row below sits near the top of the page.
Delivery
Two render modes, decided by delivery.phases.length:
- Phased mode (
delivery.phasesnon-empty): tabbed phase strip. Each tab shows “Phase N”, the status pill, title, mini progress bar, done/total count, the bar’s percentage (open bugs weighed, as above), the phase’s open bugs and the due date. Click a tab to view its detail panel. Every load opens the tab of the phase in scope (the phase row that is open above); the tab clicked is not remembered, so a reload returns to the current phase. Every panel — locked, in-progress or complete — shows the same feature rows: title, status badge (the stage written out:development,in review,shipped,decomposing), owner (a dash for a backlog feature, whose owner is not shown until work starts or it is claimed with/et-claim, or when none is set), active blockers, a progress meter weighted by phase, and last-updated. Rows sort by feature id unless a column is sorted (Column sorting, below), and a click opens the feature’s detail drawer. Data drift (acompletephase missingsealed, or a feature whosedelivery_phasedoesn’t match any phase id) surfaces inline with a ⚠ on the affected tab/row. - Flat mode (
delivery.phases: []): one-row-per-feature list grouped by sub-status, sorted bylast_updated. No phase scaffolding. Used by small projects that opt out of phases (under ~10 features).
Column sorting. The feature list, the open and closed bug lists (Signals), the foundation slice list and the Team table sort by any column: each column name is a button. Every list is always sorted by one column. Each page load starts every list on its first column: the feature list by Feature, ascending, in every phase panel; the open and closed bug lists by Bug, descending; the foundation slices by Slice, ascending; and the Team table by Team member, ascending. Clicking the sorted column reverses it; clicking another column sorts by it, ascending (smallest, oldest or A first). An arrow shows on the sorted column only, with its direction; under the pointer or keyboard focus, another column shows a faint ▲, the ascending sort a click gives. Status and severity sort by meaning, not alphabetically: a feature by its stage (backlog → … → done, then dropped and paused), a slice from not started to dropped, a bug from high to low severity and from to do to won’t fix. Ids sort naturally (F2 before F10), Updated by time, and Blocked by by the number of active blockers. Empty values go last in both directions, and rows with equal values keep the order the page built. Every phase panel shares one feature sort, so a click on any panel’s column sorts all of them; the open bug list sorts within each phase group, a feature’s detail drawer moves with its row, and the Team table’s summary rows stay at its foot. Nothing is stored: a sort chosen by clicking lasts until the page reloads, which starts every list on its first column again. Where the column names are hidden (the feature list below 1080px, the bug lists on a phone), the lists keep their current sort and cannot be re-sorted until the screen is wider.
Status chips. Every status on the page — feature and slice rows and drawers,
phase tabs, gates, risks and spikes, waves, the release
and its UAT cycles — is the same chip: an icon, the written label, and a tone
that follows how far along the item is (queued, shaping, building, review,
shipped, done, paused, dropped, plus attention and alert for risks and
failures). The tone list and what each status maps to are in index.html, beside
the .st-chip CSS and the chip() helper; a new status value needs a row in the
matching map there, or it renders as a neutral chip with its raw text.
Team (conditional)
One row per team member named in an owner field or a foundation slice’s
assignee, laid out like a ledger: currently working on (their features in
progress, then their bugs in progress, one per line with its stage as text —
F5-c · development, BUG-086 · in progress; the stage drops to its own line at
phone widths, and at 480px and below the list moves under the name), then three
counts at the right edge — foundation slices done (slices assigned to them at
done; dropped slices are not counted), features done (features they own at
ship or done) and bugs fixed (bugs they own at fixed). Every column
takes an equal share of the width, except at 360px and below, where the name
column is wider. The counts are right-aligned, headers included, so units sit under units.
Rows follow the Delivery list’s feature rows — dashed hairlines between them and
the same hover tint — while names stay in the body typeface. Above the total
row, a Dropped or won’t fix row counts the dropped slices and features and
the bugs closed as won’t fix, and a No owner recorded row (shown only when
needed) counts finished work with no owner, so the totals always match the
closed counts elsewhere on the page (the Done tiles; the slices closed while
Foundation runs, and the “Foundation slices · N” count once it is sealed). A team member is shown by full_name from
delivery.team in tracker.yaml (keyed by the first name the fields carry), or
as written when not listed there. Names sort alphabetically unless another column is
sorted (Column sorting). A feature counts
once, for its tracker owner, even when others helped. Hidden when no slice, feature or bug has one — browser-computed from
window.TRACKER.
There is no “Attention” section — paused / blocked / drift surface inline on
the feature rows they describe. Accepted risks live in project-prd.md;
scoped spikes live in design/architecture.md.
Release / UAT (conditional)
The release lifecycle, rendered from window.TRACKER.releases (one entry per
phase’s UAT round) and window.TRACKER.uat_issues — both ride the existing
regen-tracker-dashboard.sh mirror, so no new generation hook. Placed after
Delivery, before Signals (it is the stage after a phase’s delivery). Populated interactively
by the /forge-release command (or by hand). It shows one block per release,
newest first, each with the UAT issues whose release_id names it (an issue
naming no release is counted under the newest), and the section header names the
newest release that is neither signed off nor live. Each block shows:
- the release id, lifecycle status, scoped delivery phases, and the sign-off / go-live date once reached;
- a six-step lifecycle track (
build-complete → regression → uat → stabilize → signed-off → live) with the current step highlighted; - the cycle list (
RC-nregression /UC-nUAT), each with a flow pass-count (e.g.7 of 10 flows passed) and status; - a callout for any blocking UAT issues gating sign-off;
- a UAT-issue triage breakdown (total · defects · change-requests · queries · open).
The entire section hides when releases is empty ([]) — exactly like the
Usage section’s empty state, so existing projects render unchanged (NFR-1).
Detailed per-cycle plans/reports and per-flow evidence live under
.forge/release/<id>/; the tracker (and this section) hold only the compact
summary + links.
Wave Drumbeat (conditional)
A cross-feature wave-cadence view, rendered from each feature’s waves[] in
window.TRACKER. It appears (after Release / UAT, before Signals) only when at
least one feature is decomposed into waves; otherwise it stays hidden. It shows:
- in the section heading, the count of merged waves and of waves with an open PR, plus the median days from one wave’s merge to the next wave’s merge in the same feature, over the last 30 days;
- a bar chart of waves merged per day over the last 14 days;
- Merged today — each wave merged today, with its feature and the repos its work items touched;
- Live waves — every wave at
pr-open(shown “PR open”) orin-progress, with its status, the waves it waits on, and its repos. Withgithub_orgset intracker.yaml, each repo links to a GitHub PR search for that wave.
Signals (the new section)
Leading-indicator tiles that surface harness-effectiveness over time; the section heading counts them. Each tile is a single number + sub-label; no bordered cards.
| ID | Question | Source |
|---|---|---|
| S1 Phase throughput | How many features are done (shipped or dropped) in the current phase, and how many are in progress? | tracker.yaml features grouped by delivery_phase + sub-status |
| S2 Phase pace | Are we on pace, given how long previous phases took? | delivery.phases[].started + sealed (median of completed phases) |
| S3 Lead time | How long does a feature take, end to end? | Feature started → last_updated for phase: ship or done; the median, the time 3 in 4 features finish within (75th percentile), and the last-4-week trend |
| S4 Rework | Are we redoing earlier passes over shipped features? | Count of features with a non-empty follow_up_of — browser-computed from window.TRACKER (NOT signals.js) |
| S5 Paused or dropped | What share of decomposed features stopped before shipping? | “N of M”: features with phase: paused or dropped, of the features started; the sub-line splits paused and dropped |
| S6 Lessons | Is the team still in heavy learning mode, or has the workflow stabilized? | The headline is the total number of ## L-NNN lessons in .forge/lessons.md, beside a sparkline of the weekly count over the last 4 weeks — a lesson counts in a week by a dated ### YYYY-MM-DD — title heading, or a ## L-NNN — title heading’s body **Date:** line. The sub-line splits that total by status, one per line, each lesson in exactly one: awaiting upstream sync (**Sync target:** upstream, **Synced:** _pending_), synced upstream (upstream, **Synced:** names a forge-harness commit), project-only (**Sync target:** project-only), withdrawn (**Synced:** says withdrawn; the target no longer matters), and invalid (anything else — fix the entry to the format in .claude/rules/tracker.md § Lessons Entry Format). A status shows only when at least one lesson has it (all precomputed into signals.js) |
| S7 Open bugs | How many post-ship defects are open, where, and are fewer being found over time? | The headline is the count of tracker.yaml bugs[] with status open/in-progress, beside a sparkline of bugs found per week over the last 4 weeks (bugs[].found_date, in the same Monday-start UTC weeks as S6; falling is good). The sub-line gives the open bugs’ severities, the number of features or foundation slices they affect, the total filed, and the fixed and won’t-fix counts — browser-computed from window.TRACKER |
Below the tiles, four collapsed lists give the detail, each shown only when it
has entries: open bugs by scheduled-fix phase, highest id first (the phase line
is left out when every open bug is scheduled for the current phase), and closed
bugs (fixed and won’t-fix, highest id first) — each sortable by column (Column
sorting, above) and laid out as one table per list under a row of column names, so the id, severity, title, feature, owner and
status columns line up across every row; the feature column is the feature or slice
the bug was filed against (affects), the owner column is the bug’s owner (who is
fixing or fixed it, a dash while nobody has picked it up, “N/A” on a won’t-fix), the
status column is a chip in the page’s status tones (to do, in progress, fixed or won’t
fix). Each row ends in a caret and, as a feature row does, opens a drawer: status,
severity, owner, who decided a won’t-fix (decided_by), the phase the fix is scheduled
for, what it affects, when and in what it was found (found_date, found_in), what it
breaks (spec_ref), the fix PR (fix_pr, each <repo>#<n> in it a link to that pull
request in the tracker’s github_org), the write-up (the bug’s .forge/bugs.md section,
or its doc), and its notes. The drawer moves with its row when the list is sorted. On
a narrow screen the column names are hidden, the feature, owner and status move to a
line under the title, and the caret stays beside the title. Rows in
all four lists look like the Delivery feature rows: the same 8px row spacing,
12.5px text, dashed hairline between rows and hover tint. Bugs
carry a severity but no priority: delivery_phase says when the fix is due. Then
rework features with the
features they rework, and dropped features — each with its title, its phase
and its tracker notes, which record why it was dropped.
Reading the signals. These establish a baseline and surface direction — they do not (and cannot, in v1) prove the harness improved productivity. A non-harness comparison point doesn’t exist inside this dashboard. Lessons added per week (the bars on the Lessons tile) dropping over time is good (stabilization). Rework rate dropping is good; rising can be either thrashing (bad) or higher-quality specs catching more issues earlier (good) — needs human read of which. Bugs found per week (the bars on the Open bugs tile) dropping is good too, but a spike can mean a new kind of testing started (the first real Entra sign-ins produced one), not that quality fell. Phase pace is wall-clock, not effort.
Pricing never appears in the Signals section. Pricing is a local-data
feature (depends on per-developer usage.jsonl), and the rest of the
dashboard renders correctly without it — see Usage below.
Delivery Metrics (conditional)
Delivery Metrics is the estimation-baseline layer, rendered from window.METRICS
which is generated from .forge/metrics/*.jsonl ledgers. It appears after
Signals and before Usage only when at least one metrics row exists. It shows
three grouped panels plus a baseline-volume footnote:
- Cycle time — median feature cycle (
feature_started → feature_done), spec authoring (feature_started → spec_approved), wave-1 cycle (spec_approved → wave-1 merged, decomp + first build), and later-wave cycle (prev-wave merged → this-wave merged, build only). Splitting wave-1 from later waves shows how much faster waves run once the spec is paid for. - Throughput — features/day and waves/day over a rolling window (default 14
days; override with
FORGE_METRICS_WINDOW_DAYS). - Complexity signals — median workitems per feature and median agent runs.
- Baseline volume (footnote) — completed features, merged waves, agent runs (with repair/retry count), and snapshot count: the denominators behind the medians.
These are labelled as baselines / estimate signals, not predictions or
commitments. The source ledgers are append-only, role/project-level facts and are
safe to commit; future token-joined *.local.jsonl variants stay gitignored.
Usage (conditional)
A one-line current-week summary — tokens this week · est. cost · link to
usage.html — that renders only when window.USAGE has at least one
row scoped to the current project. When local usage data is absent, the
entire Usage section is hidden; no empty card, no placeholder, no “0
tokens” line. The full per-phase / per-day / per-developer / per-model
breakdown lives in usage.html (the link target), which reuses the same
usage.js data and rate table.
Pricing appears only in the Usage section and usage.html. Currency
values do not appear in the hero, KPI strip, signals, or activity rail
(FR-11 invariant — grep the rendered DOM for $ and you’ll see this).
Recent activity
The 5 most recent events derived from tracker timestamps (phase sealing/opening, feature last-updated transitions, gate runs). Listed newest-first with relative timestamps.
Privacy
usage.js and the underlying .forge/usage.jsonl are gitignored — they
contain user_email values from git config user.email and are
per-developer-per-machine local state. The three base .forge/metrics/*.jsonl
ledgers carry role/project-level delivery facts and are committed. Future
token-joined metrics variants (*.local.jsonl) are gitignored.
tracker.js, signals.js and metrics.js are gitignored too, but for a
different reason: they are generated mirrors of committed sources
(tracker.yaml, lessons.md, the metrics ledgers), and committing them would
make every branch that regenerated them conflict (.forge/lessons.md L-049).
A team-wide usage rollup across developers (a shared data store) is not part of v1.
Updating Anthropic API rates
When Anthropic changes API prices, edit the RATES block in two places, identically, and set
RATES_VERIFIED_DATE in usage.html (the only file that has it) to the day you checked:
- The inline script in
index.html(used by the Usage one-line summary). - The inline script in
usage.html(used by the cost card + by-model breakdown).
Existing rows in ~/.claude/forge-usage.jsonl need no migration — cost is
computed at render time, not at capture time. The dashboards apply the new
rates to all history on the next refresh.
Customising
Templates ship generic. To rebrand for your project, edit index.html:
- The Forge mark (inline SVG in the header)
- Colors (CSS custom properties in the
:rootblock at the top) - Section titles (“Setup”, “Delivery”, “Signals”, etc.)
tracker.js, signals.js, metrics.js and usage.js are generated — do not hand-edit.