### Install and Initialize Repo Steward Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Clone the repository, prepare the configuration file, and run the installation script. ```bash git clone https://github.com//repo-steward && cd repo-steward cp config.example.yaml config.yaml # edit: your repos, signature, limits ./install.sh # or --no-timer to only tick manually ``` -------------------------------- ### Update Model and Engine Pins Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Examples of re-running the installer to update model pins or engine configurations. ```bash STEWARD_MODEL=claude-opus-5 ./install.sh # Opus 5 on Claude Code ./install.sh # no model pin, engine back to claude STEWARD_ENGINE=opencode STEWARD_MODEL=ollama/qwen3 ./install.sh # keep both ``` -------------------------------- ### Configure AI Backends Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Specify different agentic CLI backends during the installation process. ```bash ./install.sh # Claude Code (default) STEWARD_ENGINE=codex ./install.sh # OpenAI Codex CLI STEWARD_ENGINE=gemini ./install.sh # Gemini CLI STEWARD_ENGINE=opencode STEWARD_MODEL=ollama/qwen3 ./install.sh # local models STEWARD_ENGINE=custom STEWARD_ENGINE_CMD='my-agent --prompt "$PROMPT"' ./install.sh ``` -------------------------------- ### Configure Execution Cadence and Model Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Set environment variables during installation to define the model and execution schedule. ```bash # every half hour on a strong model STEWARD_MODEL=claude-opus-5 STEWARD_CADENCE="*-*-* *:07,37:00" ./install.sh # or one bigger tick each morning (raise `limits` in config.yaml to match) STEWARD_CADENCE="*-*-* 07:00:00" ./install.sh ``` -------------------------------- ### Manage repo-steward with make targets Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Use these make commands to control the state of the repo-steward service and view logs. ```bash make status # dashboard / tick / timer state at a glance make tick # one tick, now make timer-off # pause scheduled ticks (dashboard stays up) make timer-on # resume them make logs # tail the tick log make uninstall # disable and stop every steward unit ``` -------------------------------- ### Initialize Metrics and Uptime Dashboard Source: https://github.com/alexsjones/repo-steward/blob/main/metrics.html Fetches data from the /api/metrics and /api/uptime endpoints and triggers rendering functions. Includes error handling for unreachable API endpoints. ```javascript (function () { var css = getComputedStyle(document.documentElement); function tok(n) { return css.getPropertyValue(n).trim(); } var tip = document.getElementById('tip'); function showTip(ev, html) { tip.innerHTML = html; tip.style.opacity = 1; tip.style.left = Math.min(ev.clientX + 14, innerWidth - 300) + 'px'; tip.style.top = (ev.clientY + 14) + 'px'; } function hideTip() { tip.style.opacity = 0; } function fmt(n) { if (n == null) return '–'; if (n >= 1e9) return (n / 1e9).toFixed(1) + 'B'; if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M'; if (n >= 1e3) return (n / 1e3).toFixed(1) + 'k'; return String(Math.round(n)); } function usd(n) { return n == null ? '–' : '$' + n.toFixed(2); } function day(ts) { return ts.slice(5, 10); } function hm(ts) { return ts.slice(11, 16); } fetch('/api/metrics').then(function (r) { return r.json(); }).then(render) .catch(function () { document.getElementById('tiles').innerHTML = '
API unreachable — this page needs to be served by server.py.
'; }); fetch('/api/uptime').then(function (r) { return r.json(); }).then(renderUptime) .catch(function () {}); function renderUptime(data) { var el = document.getElementById('uptime'); var urls = Object.keys(data.state || {}); if (!urls.length) { el.innerHTML = '
No sites configured — add a sites: block to config.yaml.
'; return; } var byUrl = {}; (data.samples || []).forEach(function (s) { (byUrl[s.url] = byUrl[s.url] || []).push(s); }); el.innerHTML = urls.map(function (url, ui) { var st = data.state[url]; var host = url.replace(/^https?:\/\//, ''); var hist = byUrl[url] || []; var dayAgo = new Date(Date.now() - 864e5).toISOString(); var h24 = hist.filter(function (s) { return s.ts >= dayAgo; }); var upPct = h24.length ? (100 * h24.filter(function (s) { return s.ok; }).length / h24.length) : null; var lat = h24.filter(function (s) { return s.ok && s.ms != null; }).map(function (s) { return s.ms; }).sort(function (a, b) { return a - b; }); var p50 = lat.length ? lat[Math.floor(lat.length / 2)] : null; var spark = ''; var recent = h24.slice(-100); if (recent.length > 1) { var W = 440, H = 46, maxMs = Math.max.apply(null, recent.map(function (s) { return s.ms || 0; })) || 1; var pts = recent.map(function (s, i) { return (i / (recent.length - 1) * W).toFixed(1) + ' ' + (s.ok ? (H - 4 - (s.ms || 0) / maxMs * (H - 10)).toFixed(1) : H - 2); }); spark = '' + '' + recent.map(function (s, i) { return s.ok ? '' : ''; }).join('') + ''; } return '

● ' + host + (st.ok ? '' : ' — DOWN since ' + st.since) + '

' + '

24h uptime ' + (upPct == null ? '–' : upPct.toFixed(1) + '%') + ' · p50 ' + (p50 == null ? '–' : p50 + 'ms') + ' · last ' + (st.last_status || st.error || '?') + ' in ' + (st.last_ms || '?') + 'ms

' + spark + '
'; }).join(''); } function render(data) { var usage = (data.usage || []).filter(function (u) { return !u.error; }); var metrics = data.metrics || []; // ---- totals & per-engine ---- var ENGINES = { claude: 's1', 'claude-decide': 's3', opencode: 's2', codex: 's4', gemini: 's5' }; function ec(e) { return '--' + (ENGINES[e] || 's6'); } var byEngine = {}; usage.forEach(function (u) { var e = u.engine || 'unknown'; byEngine[e] = byEngine[e] || { ticks: 0, cost: 0, in: 0, out: 0, dur: 0, engine: e }; var be = byEngine[e]; be.ticks++; if (u.cost_usd != null) be.cost += u.cost_usd; be.in += (u.input_tokens || 0); be.out += (u.output_tokens || 0); if (u.duration_ms) be.dur += u.duration_ms; }); var engList = Object.values(byEngine).sort(function (a, b) { return b.cost - a.cost; }); var totTok = 0, totCost = 0, totOut = 0; usage.forEach(function (u) { totTok += (u.input_tokens || 0) + (u.output_tokens || 0) + (u.cache_read_tokens || 0) + (u.cache_creation_tokens || 0); totOut += (u.output_tokens || 0); totCost += (u.cost_usd || 0); }); var byRepo = {}; metrics.forEach(function (m) { var r = byRepo[m.repo] = byRepo[m.repo] || { rows: [], actions: 0, newIn: 0, closedOut: 0 }; r.rows.push(m); r.actions += m.steward_actions || 0; r.newIn += (m.new_issues || 0) + (m.new_prs || 0); r.closedOut += (m.closed_issues || 0) + (m.merged_prs || 0 ``` -------------------------------- ### Initialize and Render Repository Insights Source: https://github.com/alexsjones/repo-steward/blob/main/insights.html Core JavaScript functions for managing the canvas state, rendering the repository overview, and drawing the hierarchical evidence graph. ```javascript (function(){ var graph=null,evidence={},decisions={},work={},focused=null,active=null; var canvas=document.getElementById('canvas'),detail=document.getElementById('detail'),back=document.getElementById('back'),hint=document.getElementById('hint'); function esc(v){return String(v==null?'':v).replace(/[\[&<>"'\]]/g,function(c){return {'&':'&','<':'<','>':'>','"':'"',"'":'''}[c]})} function short(name){return name.split('/').pop()} function workLabel(w,d){if(w){return {selected:'investigation queued','in-progress':'in progress','ready-for-maintainer':'proposal ready',nominated:'build queued','pr-open':'PR open',blocked:'blocked',done:'done'}[w.status]||w.status}return d?({select:'investigation selected',nominate:'build nominated'}[d.action]||d.action):''} function node(tag,cls,id,kind,title,sub,state){var el=document.createElement(tag);el.className='node '+cls;el.dataset.id=id;el.innerHTML=''+esc(kind)+''+esc(title)+''+esc(sub||'')+''+(state?''+esc(state)+'':'');el.addEventListener('click',function(e){e.stopPropagation();select(id)});return el} function repoById(id){return graph.repositories.filter(function(r){return r.id===id||r.name===id})[0]} function findNode(id){for(var r of graph.repositories){if(r.id===id)return {type:'repo',repo:r,node:r};for(var t of r.themes){if(t.id===id)return {type:'theme',repo:r,node:t};for(var i of t.ideas){if(i.id===id)return {type:'idea',repo:r,theme:t,node:i}}}}} function renderOverview(){focused=null;active=null;back.disabled=true;canvas.className='canvas overview';canvas.style.height='';canvas.innerHTML='';hint.textContent='Choose a repository to explore its evidence graph.';for(var r of graph.repositories){var n=node('button','repo posture-'+r.posture,r.id,'Repository · '+r.posture,short(r.name),r.themes.length+' themes · '+r.themes.reduce(function(a,t){return a+t.ideas.length},0)+' ideas',r.posture);canvas.appendChild(n)}if(!graph.repositories.length)canvas.innerHTML='
No repository insights have been published yet.
';showIntro()} function renderRepo(repo){ focused=repo;active=repo.id;back.disabled=false;canvas.className='canvas'; canvas.innerHTML=''; hint.textContent=repo.name+' · click any node to inspect its evidence'; var blocks=repo.themes.map(function(t){return Math.max(140,(t.ideas||[]).length*112+28)}), contentHeight=blocks.reduce(function(a,b){return a+b},0),height=Math.max(720,contentHeight+50),cursor=(height-contentHeight)/2; canvas.style.height=height+'px'; var repoY=Math.max(45,height/2-55),rn=node('button','repo posture-'+repo.posture,repo.id,'Repository · '+repo.posture,short(repo.name),repo.summary,repo.posture); place(rn,35,repoY);canvas.appendChild(rn); repo.themes.forEach(function(t,ti){ var blockTop=cursor,blockHeight=blocks[ti],ty=blockTop+blockHeight/2-48,tn=node('button','theme',t.id,'Theme · '+t.state,t.title,t.distinct_items+' distinct items',t.confidence+' confidence'); place(tn,310,ty);canvas.appendChild(tn);edge(255,repoY+52,310,ty+48,''); var ideas=t.ideas||[],ideasHeight=ideas.length*112,ideaTop=blockTop+(blockHeight-ideasHeight)/2; ideas.forEach(function(i,ii){var iy=ideaTop+ii*112,decision=decisions[i.id],queued=work[i.id],classes={select:'selected',nominate:'selected',defer:'deferred',dismiss:'dismissed'},cls='idea '+(decision?(classes[decision.action]||''):'');var n=node('button',cls,i.id,'Idea · '+i.state,i.title,i.scope,workLabel(queued,decision));place(n,615,iy);canvas.appendChild(n);edge(540,ty+48,615,iy+45,'idea')}); cursor+=blockHeight; }); ``` -------------------------------- ### Investigate site deployment failures Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md Command to list recent workflow runs for a repository to diagnose site downtime. ```bash gh run list -R --limit 10 ``` -------------------------------- ### Render Repository Metrics and Cost Tiles Source: https://github.com/alexsjones/repo-steward/blob/main/metrics.html Processes repository data to update the DOM with summary statistics and cost-per-provider tiles. ```javascript 0); }); var repos = Object.keys(byRepo); repos.forEach(function (k) { byRepo[k].rows.sort(function (a, b) { return a.ts < b.ts ? -1 : 1; }); }); var totalActions = repos.reduce(function (s, k) { return s + byRepo[k].actions; }, 0); var ticks = new Set(metrics.map(function (m) { return m.ts; })).size; document.getElementById('tiles').innerHTML = [ ['' + fmt(totTok) + '', 'total tokens'], ['' + fmt(totOut) + '', 'output tokens'], ['' + usd(totCost) + '', 'total cost'], ['' + usage.length + '', 'ticks measured'], ['' + totalActions + '', 'steward actions'], ['' + ticks + '', 'snapshots'], ].map(function (t) { return '
' + t[0] + '
' + t[1] + '
'; }).join(''); // ---- cost by provider tiles ---- var ct = document.getElementById('costTiles'); ct.innerHTML = engList.map(function (be) { var name = be.engine === 'claude-decide' ? 'decisions' : be.engine; var avg = be.ticks ? be.cost / be.ticks : 0; return '
' + '
' + usd(be.cost) + '
' + '
' + name + ' · ' + be.ticks + ' tick' + (be.ticks === 1 ? '' : 's') + (be.cost > 0 ? ' · avg ' + usd(avg) + '/tick' : '') + '
'; }).join('') || '
No usage data yet.
'; ``` -------------------------------- ### Fetch Open Issues and Pull Requests Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md Use these commands to retrieve open issues and pull requests for a specific repository. Avoid using GitHub search APIs to stay within rate limits. ```bash gh issue list -R --state open --json number,title,body,url,author,createdAt,updatedAt,labels,comments gh pr list -R --state open --json number,title,body,url,author,createdAt,updatedAt,isDraft,reviewDecision,statusCheckRollup,additions,deletions,headRefName ``` -------------------------------- ### Execute fleet-wide queue check Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md Run the tick_guard script to verify the state of all repositories before concluding an operational session. ```bash python3 tick_guard.py check --state state --config config.yaml \ --activity activity.jsonl --now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" ``` -------------------------------- ### Fetch and Initialize Insight Graph Source: https://github.com/alexsjones/repo-steward/blob/main/insights.html Retrieves insight data from the API and initializes the graph view. Requires a running backend service and a valid insight graph generated via make insights. ```javascript fetch('/api/insights').then(function(r){return r.json()}).then(function(x){graph=x.insights;evidence=x.evidence||{};decisions=x.decisions||{};work=x.proactive||{};if(!graph){canvas.innerHTML='
No validated insight graph yet.
Run make insights after collecting signals.
';return}document.getElementById('stamp').textContent='generated '+graph.generated_at.replace('T',' ').replace('Z',' UTC');renderOverview();var params=new URLSearchParams(location.search),wanted=params.get('repo'),repo=graph.repositories.filter(function(r){return r.name===wanted||r.id===wanted||short(r.name)===wanted})[0];if(repo){renderRepo(repo);var wantedNode=params.get('node');if(wantedNode&&findNode(wantedNode))select(wantedNode)}}).catch(function(){canvas.innerHTML='
Could not load the insight graph.
'}); ``` -------------------------------- ### Manage Execution Ticks Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Commands to trigger a manual tick or view system logs. ```bash make tick # run one tick now make logs # follow it ``` -------------------------------- ### Configure Canvas Event Listeners Source: https://github.com/alexsjones/repo-steward/blob/main/insights.html Sets up click event listeners for navigation and node selection on the canvas. ```javascript back.addEventListener('click',renderOverview);canvas.addEventListener('click',function(e){if(e.target===canvas&&focused)select(focused.id)}); ``` -------------------------------- ### Audit Log Event Processing and UI Rendering Source: https://github.com/alexsjones/repo-steward/blob/main/audit.html Initializes the audit dashboard by fetching events, populating filter controls, and rendering summary tiles. Requires the API to be reachable via server.py. ```javascript document.getElementById('count').textContent = evs.length + ' of ' + events.length + ' event' + (events.length === 1 ? '' : 's') + (events.length >= LIMIT ? ' (most recent ' + LIMIT + ' — the full file has more)' : ''); } function tiles() { var byActor = { maintainer: 0, steward: 0, system: 0 }; var merges = 0, decisions = 0, failures = 0; events.forEach(function (e) { if (byActor[e.actor] != null) byActor[e.actor]++; if ((e.event === 'approve' && e.data && e.data.merged) || (e.event === 'terminal' && e.data && e.data.action === 'merge' && e.ok !== false)) merges++; if (e.event === 'decision_recorded') decisions++; if (e.ok === false) failures++; }); document.getElementById('tiles').innerHTML = [ [events.length, 'events'], [byActor.maintainer, 'by you'], [byActor.steward, 'by the steward'], [merges, 'merges'], [decisions, 'decisions typed'], [failures, 'failed actions'], ].map(function (t) { return '
' + t[0] + '
' + t[1] + '
'; }).join(''); } function csv() { var cols = ['ts', 'actor', 'via', 'event', 'repo', 'ref', 'ok', 'summary', 'detail']; function cell(v) { v = v == null ? '' : String(v); return /[",\n]/.test(v) ? '"' + v.replace(/"/g, '""') + '"' : v; } var lines = [cols.join(',')].concat(filtered().map(function (e) { return cols.map(function (c) { return cell(e[c]); }).join(','); })); var blob = new Blob([lines.join('\n') + '\n'], { type: 'text/csv' }); var a = document.createElement('a'); a.href = URL.createObjectURL(blob); a.download = 'decision-log.csv'; a.click(); URL.revokeObjectURL(a.href); } document.getElementById('dl-csv').addEventListener('click', csv); fetch('/api/audit?limit=' + LIMIT).then(function (r) { return r.json(); }).then(function (res) { events = res.events || []; function fill(id, label, key) { var seen = {}; var vals = events.map(function (e) { return e[key]; }) .filter(function (v) { return v && !seen[v] && (seen[v] = 1); }).sort(); var sel = document.getElementById(id); sel.innerHTML = '' + vals.map(function (v) { return ''; }).join(''); sel.addEventListener('change', render); } fill('f-actor', 'all actors', 'actor'); fill('f-event', 'all events', 'event'); fill('f-repo', 'all repos', 'repo'); var dateEl = document.getElementById('f-date'); dateEl.value = new Date().toISOString().slice(0, 10); dateEl.addEventListener('change', render); document.getElementById('f-q').addEventListener('input', render); tiles(); render(); }).catch(function () { document.getElementById('list').innerHTML = '
API unreachable — this page needs to be served by server.py.
'; document.getElementById('tiles').innerHTML = ''; }); })(); ``` -------------------------------- ### Fetch Repository Discussions Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md Retrieve discussions using GraphQL when enabled for the repository. Skip the query if the repository does not support discussions. ```graphql gh api graphql -f query='query($o:String!,$n:String!){repository(owner:$o,name:$n){ discussions(first:30,orderBy:{field:UPDATED_AT,direction:DESC}){nodes{ number title bodyText updatedAt url author{login} category{name} isAnswered comments(last:3){totalCount nodes{author{login} updatedAt bodyText}}}}}}' \ -f o= -f n= ``` -------------------------------- ### Generate SVG Charts for Repository Metrics Source: https://github.com/alexsjones/repo-steward/blob/main/metrics.html JavaScript logic to render SVG charts for repository usage and steward actions. Requires existing DOM elements with IDs 'attnChart' and 'repoTrends'. ```javascript y2="' + y + '"/>' + '$' + (maxC * f).toFixed(0) + ''; }); var step = (CW - CP.l - CP.r) / Math.max(1, usage.length - 1); engineOrder.forEach(function (e, ei) { var pts = series[e].map(function (v, i) { return (CP.l + i * step).toFixed(1) + ' ' + (CH - CP.b - (v / maxC) * (CH - CP.t - CP.b)).toFixed(1); }); csvg += ''; var lastV = series[e][series[e].length - 1]; var lx = CP.l + (series[e].length - 1) * step; var ly = CH - CP.b - (lastV / maxC) * (CH - CP.t - CP.b); csvg += '' + (e === 'claude-decide' ? 'decisions' : e) + ' $' + lastV.toFixed(2) + ''; }); csvg += '' + day(usage[0].ts) + '' + '' + day(usage[usage.length - 1].ts) + ''; cc.innerHTML = '

' + engineOrder.map(function (e) { return '' + (e === 'claude-decide' ? 'decisions' : e) + ''; }).join('') + '

' + csvg; } // ---- attention by repo (horizontal bars) ---- var ac = document.getElementById('attnChart'); var ranked = repos.map(function (k) { return { repo: k, actions: byRepo[k].actions, newIn: byRepo[k].newIn }; }) .sort(function (a, b) { return b.actions - a.actions || b.newIn - a.newIn; }); if (!ranked.length) { ac.innerHTML = '

No snapshots yet.

'; } else { var maxA = Math.max.apply(null, ranked.map(function (r) { return r.actions; })) || 1; var rh = 26, W2 = 1040, L2 = 150; var svg2 = ''; ranked.forEach(function (r, i) { var y = i * rh + 4; var w = Math.max(2, r.actions / maxA * (W2 - L2 - 60)); svg2 += '' + r.repo + '' + '' + '' + r.actions + ''; }); svg2 += ''; ac.innerHTML = '

Cumulative steward actions (reviews, triage replies, staged items) — the best available proxy for where attention goes; token usage is recorded per tick, not per repo

' + svg2; ac.querySelectorAll('rect').forEach(function (r) { r.addEventListener('mousemove', function (ev) { var d = ranked[+r.dataset.i]; showTip(ev, d.repo + '
' + d.actions + ' steward actions
' + d.newIn + ' new items since baseline'); }); r.addEventListener('mouseleave', hideTip); }); } // ---- per-repo trends (small multiples, 2 lines each) ---- var rt = document.getElementById('repoTrends'); var trendRepos = repos.map(function (k) { var last = byRepo[k].rows[byRepo[k].rows.length - 1]; return { repo: k, vol: (last.open_issues || 0) + (last.open_prs || 0) }; }).sort(function (a, b) { return b.vol - a.vol; }).slice(0, 6); var snaps = Math.max.apply(null, repos.map(function (k) { return byRepo[k].rows.length; })); if (snaps < 3) { rt.innerHTML = '
Trend lines appear once three snapshots exist — currently ' + snaps + '.' ``` -------------------------------- ### Verify Systemd Environment Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Check the current environment variables configured for the systemd service. ```bash systemctl --user show repo-steward.service -p Environment ``` -------------------------------- ### Reconcile open decisions via GitHub CLI Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md Commands to check the status of PRs and issues to determine if they should be marked as resolved. ```bash gh pr view -R --json state,mergedAt ``` ```bash gh issue view -R --json state ``` -------------------------------- ### Execute Maintainer Decision via API Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md CURL command to request a merge or close action from the local server. ```bash curl -s -X POST http://localhost:8377/api/terminal \ -d '{"action":"merge","repo":"owner/repo","kind":"pr","number":650,"reason":"maintainer decision "}' ``` -------------------------------- ### System Workflow Diagram Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Visual representation of the systemd-driven tick cycle and the interaction between the dashboard, server, and Claude-based automation. ```text systemd timer (hourly) you, on the dashboard │ type a decision ⏎ / ✓ approve & merge ▼ │ tick.sh ── drains typed decisions first ▼ │ server.py (systemd, port 8377) ▼ records → decisions.jsonl claude -p "execute one steward tick" spawns decide.sh when idle │ executes gh actions under YOUR auth ├─ sync: gh polls each repo since last cursor ├─ triage new issues → classify, label, draft substantive replies ├─ join discussions → draft replies to unanswered threads (GraphQL) ├─ review PRs → verdicts: approve-recommend / iterate / escalate ├─ delta re-review PRs whose authors pushed since last review ├─ author fix PRs for confirmed bugs (own clones, tests included) ├─ escalate tie-breaks to escalations.md — never blocks on them ├─ write ledgers + metrics, regenerate dashboard.html └─ snapshot changed evidence into signals.jsonl for later insights ``` -------------------------------- ### Activity Log Entry Schema Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md JSON line format for recording discrete actions or observations in the activity log. ```json {"ts":"","kind":"posted","repo":"llmfit","ref":"pr-583","summary":"posted delta re-review — approve-recommend","ok":true,"data":{"review_record_id":"rr-583-a1b2c3"}} ``` -------------------------------- ### Render Repository Trend Charts and Tables Source: https://github.com/alexsjones/repo-steward/blob/main/metrics.html This script processes repository data to generate SVG trend charts and an HTML table displaying issue and PR statistics. ```javascript Each tick adds one.
'; } else { rt.innerHTML = trendRepos.map(function (t, ti) { var rows2 = byRepo[t.repo].rows; var W3 = 480, H3 = 140, P3 = { l: 34, r: 46, t: 10, b: 18 }; var maxV = Math.max.apply(null, rows2.map(function (m) { return Math.max(m.open_issues || 0, m.open_prs || 0); })) || 1; function pts(key) { return rows2.map(function (m, i) { var x = P3.l + i / Math.max(1, rows2.length - 1) * (W3 - P3.l - P3.r); var y = P3.t + (1 - (m[key] || 0) / maxV) * (H3 - P3.t - P3.b); return [x, y]; }); } function path(p) { return p.map(function (q, i) { return (i ? 'L' : 'M') + q[0].toFixed(1) + ' ' + q[1].toFixed(1); }).join(''); } var pi = pts('open_issues'), pp = pts('open_prs'); var lastI = pi[pi.length - 1], lastP = pp[pp.length - 1]; var svg3 = ''; [0, 1].forEach(function (f) { var y = P3.t + (1 - f) * (H3 - P3.t - P3.b); svg3 += '' + '' + Math.round(maxV * f) + ''; }); svg3 += '' + '' + '' + '' + '' + rows2[rows2.length - 1].open_issues + '' + '' + rows2[rows2.length - 1].open_prs + '' + '' + day(rows2[0].ts) + '' + '' + day(rows2[rows2.length - 1].ts) + ''; return '

' + t.repo + '

' + '
issues' + 'PRs
' + svg3 + '
'; }).join(''); } // ---- table (accessibility + exact numbers) ---- var tbl = document.getElementById('repoTable'); var trs = repos.map(function (k) { var rows3 = byRepo[k].rows, last = rows3[rows3.length - 1], first = rows3[0]; var dI = (last.open_issues || 0) - (first.open_issues || 0); var dP = (last.open_prs || 0) - (first.open_prs || 0); function delta(n) { return n === 0 ? '±0' : (n > 0 ? '+' + n : String(n)); } return { k: k, last: last, dI: dI, dP: dP, a: byRepo[k].actions, delta: delta }; }).sort(function (a, b) { return (b.last.open_issues + b.last.open_prs) - (a.last.open_issues + a.last.open_prs); }); tbl.innerHTML = '' + '' + trs.map(function (r) { return ''; }).join('') + '
repoopen issuesΔ since baselineopen PRsΔawaiting youescalationssteward actions
' + r.k + '' + (r.last.open_issues || 0) + '' + r.delta(r.dI) + '' + (r.last.open_prs || 0) + '' + r.delta(r.dP) + '' + (r.last.awaiting_maintainer || 0) + '' + (r.last.escalations_open || 0) + '' + r.a + '
'; } })(); ``` -------------------------------- ### Record repository metrics Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md Append a single line of JSON metrics per repository to the metrics.jsonl file. ```json {"ts":"","repo":"","open_issues":N,"open_prs":N,"new_issues":N,"new_prs":N,"closed_issues":N,"merged_prs":N,"awaiting_maintainer":N,"escalations_open":N,"steward_actions":N,"oldest_unanswered_days":N} ``` -------------------------------- ### Evaluation JSON Schema Source: https://github.com/alexsjones/repo-steward/blob/main/EVALUATION.md The required structure for the evaluation.candidate.json output file. ```json { "v": 1, "generated_at": "", "posture": "improving|stable|needs-attention|insufficient-data", "summary": "critical overall assessment", "dimensions": [{ "key": "pr-review-quality", "title": "PR review quality", "status": "improving|stable|needs-attention|insufficient-data", "summary": "what the evidence supports", "signal_ids": ["sig_..."] }], "findings": [{ "key": "stable-kebab-case-key", "repo": "owner/repo|_portfolio", "category": "issue-triage|discussion-response|pr-review|escalation|insight-analysis|proactive-work|calibration|process", "assessment": "supported|mixed|contradicted|inconclusive", "confidence": "low|medium|high", "title": "specific finding", "original_judgment": "what the steward believed or did", "observed_outcome": "what happened later", "critique": "where the reasoning was strong or weak", "recommendation": "specific change to future reasoning", "signal_ids": ["sig_...", "sig_..."] }], "lessons": [{ "key": "stable-kebab-case-key", "repo": "owner/repo|_portfolio", "guidance": "short actionable guidance for future ticks", "applies_to": "when this guidance is relevant", "confidence": "low|medium|high", "finding_keys": ["key-above"] }] } ``` -------------------------------- ### Query Audit Log with jq Source: https://github.com/alexsjones/repo-steward/blob/main/README.md Use jq to filter and format terminal action events from the audit.jsonl log file. ```bash jq -r 'select(.event=="terminal") | "\(.ts) \(.repo) \(.ref): \(.summary)"' audit.jsonl ``` -------------------------------- ### Generate Token Usage SVG Chart Source: https://github.com/alexsjones/repo-steward/blob/main/metrics.html Creates an SVG bar chart representing token usage per tick with interactive tooltips. ```javascript // ---- tokens per tick (bar, single series; tooltip = breakdown) ---- var uc = document.getElementById('usageChart'); if (!usage.length) { uc.innerHTML = '

No usage recorded yet — token capture starts with the next tick (recorded by tick.sh into usage.jsonl).

'; } else { var W = 1040, H = 180, P = { l: 46, r: 8, t: 12, b: 22 }; var rows = usage.slice(-40); var max = Math.max.apply(null, rows.map(function (u) { return (u.input_tokens || 0) + (u.output_tokens || 0) + (u.cache_read_tokens || 0) + (u.cache_creation_tokens || 0); })) || 1; var bw = Math.min(34, (W - P.l - P.r) / rows.length - 2); var svg = ''; [0, 0.5, 1].forEach(function (f) { var y = P.t + (1 - f) * (H - P.t - P.b); svg += '' + '' + fmt(max * f) + ''; }); rows.forEach(function (u, i) { var tot = (u.input_tokens || 0) + (u.output_tokens || 0) + (u.cache_read_tokens || 0) + (u.cache_creation_tokens || 0); var x = P.l + i * ((W - P.l - P.r) / rows.length) + 1; var h = Math.max(2, tot / max * (H - P.t - P.b)); var y = H - P.b - h; svg += '' + '' + hm(u.ts) + ''; }); svg += ''; uc.innerHTML = '

One bar per tick · hover for the input/output/cache breakdown, cost, and duration

' + svg; uc.querySelectorAll('rect').forEach(function (r) { r.addEventListener('mousemove', function (ev) { var u = rows[+r.dataset.i]; showTip(ev, '' + (u.engine || '?') + '
' + u.ts.replace('T', ' ').replace('Z', ' UTC') + '
in ' + fmt(u.input_tokens) + ' · out ' + fmt(u.output_tokens) + '
cache read ' + fmt(u.cache_read_tokens) + ' · write ' + fmt(u.cache_creation_tokens) + '
cost ' + usd(u.cost_usd) + ' · ' + (u.duration_ms ? Math.round(u.duration_ms / 60000) + ' min' : '–') + ' · ' + (u.num_turns || '–') + ' turns'); }); r.addEventListener('mouseleave', hideTip); }); } ``` -------------------------------- ### Progress Feed JSON Schema Source: https://github.com/alexsjones/repo-steward/blob/main/STEWARD.md JSON lines used to track repository progress and substantive items throughout a tick. ```json {"phase":"repo","repo":"llmfit","msg":"reviewing PRs"} {"phase":"item","repo":"llmfit","ref":"pr-583","msg":"delta re-review → iterate"} ```