Changes

The Changes screen is a diary of what changed in your repos, week by week. Your boards show the system as it is; Changes shows what moved on it, and who the move reaches. Each diary entry is one piece of work in one repo's week: what it did, where it landed, who did it, and the change rules it hit.

The code plugin records each week from git, on every scheduled /analyze or with /changes. The Diary and Diary entries cards on the root hub and on each app hub show the same entries, and every other way into a change opens here.

Expand

1. 1

   The weeks

   A bar's height is that week's commits, and the dots above it mark its highest-ranked entries.

2. 2

   Filters and the app picker

   Four filters narrow the list, each with its count, and on the root board a picker narrows it to one app.

3. 3

   The open entry

   Select an entry to open it beside the list.

Set up

Schedule /analyze --scheduled in each app's repo as a scheduled run. Each run refreshes the boards whose code changed, syncs them, and records the weeks since the last run. The diary keeps up with the code without anyone running a command.

The first run reads the git history back as far as the workspace's Read history back setting, 90 days by default, and records one change period per week. After that, each run records the weeks since the last one and rewrites the current one.

To record the weeks straight away, or in a repo without a schedule, run /changes. It records the same change periods without refreshing the boards.

Expand

Four Reporting settings shape the diary. Three are Change periods (weeks or calendar months), Read history back and Keep change periods. The fourth, Look back, sets how far back a node's diary entries reach and how old a period can be and still raise a flag. See Workspace Settings.

Record the weeks

A change period is one repo's record of one week or month. It holds the commits, who made them with which coding agent, each change rule's answer, and the pieces of work the commits group into. /changes reads the bound branch's history and records every period ProvenMap doesn't have yet. A closed period already recorded is skipped; the current one is rewritten each time.

/changes                       # record every period not yet recorded
/changes --since 2026-01-01    # read further back than the workspace's history setting, once
/changes --recompute           # rewrite closed periods already recorded
/changes --facts-only          # record the facts, with no sentences

/changes groups a week's commits into pieces of work, and each piece becomes one diary entry:

• A commit joins the piece named by its conventional-commit scope: feat(hub): … joins hub.
• A commit with no scope joins the node most of its files belong to.
• The rest go into other changes.

A repo keeps at most eight pieces of work a week, the largest first. The diary counts the commits in the smaller ones it left out.

Expand

The agent running the command writes the words: each piece's headline and what it did, and for each rule it hit, its impact. It also writes what changed for each rule answered Changed. Each sentence names an area of work, never an amount, and never compares people; anything the commit messages can't support is left empty. A scheduled run writes them for every period it records, the same as /changes.

Commit messages and the full file lists stay on your machine. Only the record is pushed: the counts, the sentences, and at most five names and five paths per rule. The code plugin covers what /changes reports and where the other commands mention it.

Read the diary

The Changes tab is on every app board and on the root board. Its Diary tab lists the entries of every week the period control reaches; on the root board it covers every app in the tree.

Watch: record a repo's weeks, read the diary, and follow a change to the apps it reaches

The row of bars at the top is the weeks the period control reaches, or months on a workspace that reports monthly. A bar's height is that week's commits, and its lower part is the commits that name a coding agent. The dots above a bar mark its highest-ranked entries, so you can see which week to open before you open it. Select a bar to list only its entries, and select it again to go back to the whole period.

Four filters narrow the list, each with its count:

• All: every entry.
• Contracts: entries that hit Schema or API contract.
• Breaking or flagged: entries marked Flag to review or Breaks callers.
• Your rules: entries that hit a rule your organization added.

On the root board, when more than one app has entries, a picker also narrows the list to one app.

Entries are ranked by their mark, then by commits:

Each row gives the headline, what the work did, its commits and how many name an agent, and who did it. A chip per rule shows its impact, such as API contract · breaking. An entry that changed a contract also names the other apps that depend on what it touched, such as Portal and Plugins depend on it. Where no app can be named, it says how many systems depend on its app instead.

Under the list, a line counts the commits in smaller pieces of work no entry lists. On the root board, Worked these weeks names each app with its commits. With one week selected, it reads Worked this week. Nothing recorded names each app with no period in those weeks, and the date of its last one. An app there hasn't run /changes, which isn't the same as doing nothing.

Point at an entry with the board map open, and the map rings the boards it landed on. With the map closed, the Map button rings once instead, so you know there is something to see. While the diary is open, the map also shows each app's commits for the listed weeks beside its row.

Entries that aren't a piece of work

A week recorded before /changes grouped commits into pieces of work has one entry per rule that answered Changed, with no people and no impact. A rule answered Changed that no listed piece of work hit gets an entry of its own. Structure, answered from pushes, is the usual one.

Open an entry

Select an entry to open it beside the list, or under its row on a narrow screen. Its header gives the mark, the app, the week, the headline and what the work did, then its commits and what grouped them, shown as grouped as hub.

Expand

Below the header, in order:

• Where it landed: the nodes its files belong to. Select one to open it on the canvas. A node the analysis no longer has is shown dashed.
• Who: each person with the coding agent their commits name.
• Who depends on it · today: shown only when the entry changed a contract. It lists the systems that depend on the app's system, then those one step further out, each with the system in between, such as Storefront · through Orders. See Who depends on a change.
• Reaches other apps · today: shown when the entry changed a contract. Each app that depends on what the work touched, with its clients, subscribers or readers, and the endpoints, events or tables they go through. It lists up to six apps and three of each per app, then counts the rest. Select an app to open its hub. See What in other apps a change reaches.
• Rules it hit: each rule with its impact, the names and paths behind it, and Mark reviewed on an open flag. A rule your organization added reads your rule. Under the rules, Asked for lists the work items the commits cite, when the repo cites work items at all.

Impact

The agent running /changes writes one word for each rule a piece of work hit, from its commits:

When the commits don't say which, the rule reads impact not written.

Who depends on a change

Who depends on an app comes from two places: the calls and events adopted from each app, and the edges drawn between systems on the root canvas. It is read when you open the entry, not when the change was recorded, which is why the section says today. People and roles drawn on the canvas, such as an end user, aren't counted: they use a system rather than depend on its contract. With neither source, the entry says nothing shows who depends on the app, rather than claiming nobody does.

What in other apps a change reaches

Who depends on it answers for the app as a whole. Reaches other apps answers for what the change touched, element by element, from the aspects each app adopted:

A change reaches these two ways:

• A table the Schema rule named, read from the changed migration. This is the exact table.
• An endpoint or event served by a node the work landed on, or by a node in its layer. The change may not have touched that endpoint, so the section says Served by a node this work landed on; the change may not touch these parts.

Expand

Edges drawn on a canvas aren't followed: they say an app depends on another, not on which part. Only a change that hit Schema or API contract is checked. Like who depends on a change, it is read when you open the entry, which is why the section says today. When it finds nothing, it says no adopted client, subscriber or reader in another app depends on what the change touched. An app counts once its clients, events or tables are adopted with /aspects.

On an app hub, the Diary entries card has a From other apps filter. It lists the changes in other apps over the hub's period that reach this one, up to 20, newest first. Each one's View detail opens it on the Changes screen of the app that made it.

Review a flag

Infrastructure is critical: a Changed answer raises a flag. The entry ranks first as Flag to review. The app hub's attention queue and the root hub's Fleet attention each get a row for it. Open change on the row opens the entry.

Choose Mark reviewed beside the rule in the entry, or on the attention queue's row. The rule then reads Reviewed with the date and who reviewed it. A flag is raised only for a period that ended inside the workspace's Look back window, so recording last year's history doesn't fill the queue.

A review holds when /changes rewrites the open week and the rule's answer is the same: the same names, paths and counts. New evidence opens the flag again.

Expand

Other ways in

Every other place that tells a change opens it on the Changes screen:

• The Diary entries card on a hub: View detail on an entry, or Open in Changes.
• The attention queue and Fleet attention: Open change on a flag's row.
• A push session's footprint: What changed names the week the push landed in and opens that repo's entries for it.
• The node inspector: a node that diary entries name shows In N diary entries with the newest. Select it to open it, or open the app's Changes.
• The System scorecard: its three change cells open Changes.
• The Monday briefing: each entry it names links to it.

People and agents, and Busy services

The People and agents and Busy services tabs read the same change periods, by app, over the period the control in the screen's header sets. Change Cards covers what each shows.

Change rules

A change rule is a question each period answers about what changed, with Changed or No change. Four are provided:

Rules your organization adds run beside these, and the Your rules filter shows the entries that hit them. A rule answered from files gives the same answer on every run. Its names come from the file names, so a migration named 0042_add_idempotency_keys.sql reads "add idempotency keys". In a period with no sync in it, the Structure rule has no answer, and the diary makes no entry from it.

Add or change a rule

Note

Owners and admins only. Everyone else sees the rules read-only.

Your organization's rules are in Organization settings → Change Rules, one list for every repo. /changes reads them on each run, so a change reaches every repo on its next run.

Expand

1. 1

   Rules on

   At most eight rules are on at once, and the header counts them.

2. 2

   The switch

   The switch beside a rule turns it off or on.

3. 3

   Customize (the pencil)

   Choosing Customize saves your organization's own copy, marked Customized.

Choose New rule and fill in its Name, a Slug (fixed once saved), the Question it asks and what it's Answered from. In When the answer is Changed, say what the agent running /changes should write about the change, up to 600 characters. A rule is answered from one of two places:

Turn on Critical and a Changed answer raises a flag. The switch beside a rule turns it off or on; at most eight rules are on at once, and the header counts them, such as 4 of 8 on.

Each rule is marked Provided, Customized or Your rule. A provided rule can be switched off but not deleted. Choosing Customize saves your organization's own copy, marked Customized, and Reset to provided brings the provided rule back. Edit changes a rule your organization added, and Delete removes it.

Periods already recorded keep the answers they were given. The next /changes run answers with the edited rule, and /changes --recompute rewrites the closed periods with it.

Work items behind a piece of work

/changes reads the work item numbers a commit message cites, #12 or WI-12, anywhere in it. It skips the (#4480) GitHub adds to a squash merge, which names the pull request. ProvenMap keeps a number only when it names a work item on that app's own boards, created before the period ended.

An entry lists those work items under Asked for. The list shows only for a repo whose commits cite work items at some point in the diary's weeks. In a repo that never cites them, an empty list would say nothing. The System scorecard counts the periods with commits and no work item behind them; a work item a push in the period completed or verified counts too.

Limits

• The bound branch only. Work on other branches counts once it is merged.
• History moves with git. A rebase moves commits between periods; a squash merge drops co-authors the squash didn't keep.
• A shallow clone can't reach the start of a period, so that period's counts are incomplete.
• Nodes are mapped with today's analysis, so a renamed service counts under its current name.
• Coding agents are recognised from a fixed list of the names and addresses they commit under, as the author or in a Co-Authored-By trailer: Claude, Codex, Cursor, Copilot and others. Each shows under one name, whatever model or version signed. A commit no listed agent authored or co-signed names no agent.
• A piece of work is a grouping by scope or node, not by intent. Two pieces of work under one scope are one entry.
• Per piece of work: 5 nodes, 4 person-and-agent pairs, 10 cited work items and an 80-character headline.
• Per period: 8 pieces of work, 10 person-and-agent pairs, 20 services, 5 names and 5 paths per rule, 20 cited work items, and 400 characters per sentence. Past a cap, the record counts the people and services it left out, and the diary counts the commits in the pieces of work it left out. Names, paths and work items past a cap are dropped.

FAQ

What's next