004 Measurement

004 Measurement

Status: Draft — may change (2026-10-19)

1. The question

The owner renamed Module 004 Measurement and moved the project analysis (commitment 1) to 008 Planning under an owner decision; the number, folder and citation keys stay 004. This draft carries the move out: commitment 1's material is folded into 008's chapter I, its number is retired here, not re-used, and the module stands alone as Measurement.

A team is sized, shaped, changed and judged by someone. RFC 004 asked on what: what TeamCLI looks at, what it says it found, and how far that can be relied on. Since then the Kernel has fixed that a finding commands nothing (a reserved object changes only through the owner or a grant holder, §3) and that reading is bounded by what a seat may see (§9, §12); the Runtime keeps the records an analysis would read (commitment 26) and the machine's readings (commitment 14); 010 times every step of a round and asks for a daily report (commitment 18); 005 asks what each check cost and found (commitment 8); 008 keeps the plan's time (commitment 12); and the owner has drawn one line by decision: team usage reports tokens only, availability is a command of its own, and the registry keeps every agent that worked on a project so a team's cost is known at any time (an owner decision). So the module's question is the remainder: what is read, by whom, to say what a team's work took and cost, how each agent and lab did on this work, whether the team's shape fits its work and the plan fits what happened; with every finding sourced, measured from what was seen, and acted on only by whoever holds the right?

2. What we propose

Thirteen commitments in four chapters. Chapter A keeps the measurement subjects, chapter B the four rules that 005, 008 and 010 cite instead of restating them (an owner decision), chapter C the settings, chapter D the records the module reads — the inputs tonight's decisions gave it. No capability or refusal is added (Kernel §13). The commitment numbers are RFC 004's, kept; commitment 1 moved to 008's chapter I under an owner decision and its number is retired; the input commitments take the next free numbers, 11 to 14.

A. What is measured

2. A team's work, while it runs and after. TeamCLI MUST measure what was asked and delivered, how long each thing took and how long it waited and on whom, how often work came back from a check, where the team stood still, and what it cost — with the delivery outcomes and the release history beside them (an owner decision). The records are the Runtime's and 008's; the reading is this module's. Spec: Specs-registry (the records), Specs-tasks-and-broker (the lease). Proof: src/labels/state.ts, src/log.ts, src/tasks/lease.ts; analytical proof none yet. Today (v0.5.0). State, log and usage observations exist; no delivery/queue timing analysis or pull history.

3. Each agent, and each lab, on this work. TeamCLI MUST measure which agent did which kind of work well on this project, how often each was stopped by a limit, and what each cost for what it delivered — on this work, never on a public test. A comparison says what each was given to do; where the work given was not alike it says "not comparable" and gives no ranking (that is what "not comparable" is computed from, the question §10.5 asks the round to test). Spec: Specs-budgets (the cost views). Proof: src/information/usage.ts; test/usage-quota.test.ts for readings only. Today (v0.5.0). Usage windows and provenance exist; no performance comparison or cost attribution. team usage reads every team's accounts and windows on the machine, what is left and used, when each figure was last read and from which source, tokens only (an owner decision); the registry's cost view (a record outliving membership) is planned (Runtime commitment 3).

4. A team's shape, against its work. TeamCLI MUST relate what the watch observes to the team's shape: an agent that waits all day, a kind of work nobody takes, one agent everything waits on, a team larger than its work; each said with what was observed and what a different shape would be expected to change. Spec: Specs-seat-state-and-watch (the checks). Proof: src/watch/checks/idle.ts, team-idle.ts; analytical proof none yet. Today (v0.5.0). Watch observes idle states; no shape/work comparison. The thresholds of the watch (Runtime commitment 20), sixteen checks (seat-state-and-watch.md §3.3), and the idle thresholds an owner decision resolved and once-per-idle-period owner escalation (src/watch/checks/idle.ts:7–10,30–37) are built at v0.5.0, while team-shape analysis is not built.

5. The plan, against what happened. TeamCLI MUST set each estimate beside the real time, and say which kinds of work are always late and by how much. The estimate and the deadline are 008's (commitment 12); the comparison is this module's. Spec: Specs-tasks-and-broker (the task records). Proof: src/commands/plan.ts, src/tasks/adapter.ts; test/plan.test.ts. Today (v0.5.0). No estimate; plan display marks overdue dates against the clone's clock and never acts on them (008 commitment 12).

B. What holds for every measurement

The four rules. 005, 008 and 010 cite them here instead of restating them (an owner decision).

6. Every finding carries its source. A finding MUST name what was observed, when, and by what; where nothing was observed it says "not known", and an estimate says it is one and what it rests on. A finding that cannot be traced is an opinion, and TeamCLI does not present one as the other. A wrong finding is corrected by the owner and keeps the trace of its correction. Shared with 005 commitment 5 (a check says what it looked at): one rule, two readers. Spec: Specs-seat-state-and-watch (the typed lines). Proof: src/information/quota.ts; test/usage-quota.test.ts for readings only. Today (v0.5.0). Usage reports source and age; general finding/correction record unbuilt.

7. A team is measured from what TeamCLI saw, not from what agents say of themselves. An agent's report and a lab's figures MUST remain one source, named as such, never the measure. An agent that is judged by its own reports learns to write reports. Spec: Specs-seat-state-and-watch (the state ranking), Specs-budgets. Proof: src/labels/state.ts, src/information/quota-observe.ts; test/seat-state.test.ts, test/usage-quota.test.ts. Today (v0.5.0). The seat state is ranked from what the tool reads — the held note and the hooks first, and the trace last, except that in src/labels/state.ts:78–82,132–147 a recent trace takes priority over an idle hook, screen or herdr word while blocking conditions still win (Runtime chapter C); the usage figures are screen readings, never seat counts.

8. A measurement says, and does not decide. A finding MUST go to whoever may act on it; a proposal is never the act. What a measurement reads does not command it and a finding changes nothing by itself are the Kernel's (§3: a reserved object changes only through the owner or a grant holder; §11: integrity is not authority); what stays here is the shape: a finding that starts a proposal does so only where the owner set it to. Spec: Kernel §§3, 11 (cited, not moved). Proof: src/commands/check.ts; test/check-repair.test.ts for repair only. Today (v0.5.0). No analysis decision engine; team check --repair makes one repair, the owner's, and prints every other (Runtime commitment 13).

9. You choose who does the looking, and what is kept. Where a measurement comes from (the tool's own, a trusted tool, the tracker's or a lab's figures) MUST be set by the owner, a finding MUST say which produced it, and what is kept MUST be files the owner can read and remove. A measurement MUST NOT run until the owner, or a seat given that right beforehand, has named who looks and what it may read. Removing kept records MUST stop TeamCLI using them; it does not take them out of what a lab already read. Analysing is a right of its own is the Kernel's vocabulary question (§4, question 2: reading a project is the widest read there is; which capability covers it, and §12's containment bounds it); a lab allowed only public material analyses only that is the Kernel's visibility. Spec: Kernel §§3, 6, 9, 12, 13 (cited, not moved). Proof: src/commands/usage.ts, src/information/machine-readings.ts; test/usage-machine-readings.test.ts. Today (v0.5.0). Usage has a restricted/full caller view; machine figures omit team, seat, path and screen text; the usage readings are kept in the owner's own configuration folder, named by the command page. No general analysis-source/retention setting.

C. Settings

10. All of it is yours to set. What is measured and how often, who is told, what is kept and for how long, whether a finding may start a proposal unasked (by default it may not): each MUST sit in the catalogue's form (the Kernel's Policies section), inheriting entity, project, team, seat, tightening only. Spec: Specs-policies (the policy object and the chain). Proof: src/policy/types.ts; none yet. Today (v0.5.0). No analysis-policy family exists; daily-report is a planned policy row for 010, not in the code (src/policy/types.ts).

D. What it reads

The inputs, from the decisions of 2026-10-18 and 2026-10-19. The records themselves are the Runtime's, 002's and 008's; this module reads them and is read by 008's casting.

11. The session registry: who worked, when, and at what cost. Measurement MUST take its facts of who worked on what, when, on which model and at what cost from the registry's session records (an owner decision): one record per session under its seat, written by TeamCLI itself at up, restart, the swap and down, never from the agent's word, so the figures of commitments 2 and 3 rest on records no agent wrote. The record's fields and lifecycle are those in Specs-registry §3.7 (the session record, planned at v0.5.0; an owner decision); this text adds none. Spec: Specs-registry §3.7 (the session record, planned at v0.5.0; an owner decision). Proof: none yet. Today (v0.5.0). Not built at v0.5.0 beyond team usage's readings: no session records are written; until they are, the records are kept by hand (an owner decision).

12. Cost by entity, project, team, seat and agent. Measurement MUST roll cost up along the registry's hierarchy — agent (the occupant's session), seat, team, project, entity — in tokens and, where known, in money; a figure that is not exposed MUST stay "unknown", never zero (an owner decision). Money figures come from the entity's accounts, stated as such. Spec: Specs-budgets (the sources per CLI, the views and the staged plan). Proof: src/information/usage.ts for token readings only; none for the roll-ups. Today (v0.5.0). Not built at v0.5.0 beyond team usage, which reports tokens only (an owner decision); the --by views and per-turn cost are the decision's staged plan.

13. Every channel's speed and failures. Measurement MUST measure, per channel, the latency of each stage of a round trip and the failure rate, from the timestamps the communication module's envelope is designed to carry (messaging.md §3, the at map, one per stage; planned at v0.5.0) (two owner decisions; 002's chapter on adapters, envelope and router). A latency target is set from the measurement, not before it. Spec: Specs-messaging (the envelope's fields). Proof: none yet. Today (v0.5.0). Not built at v0.5.0: no per-stage timestamps are kept anywhere in the code at the tag; per-stage measurement is the decisions' plan.

14. A cast's results, fed back. Measurement MUST give the casting its measured results — rounds to pass, work returned, cost per task (an owner decision) — so the next cast weighs how the last one did, once the session registry exists. The casting itself is 008's; the numbers are this module's. Spec: Specs-tasks-and-broker (the task records the numbers come from). Proof: none yet. Today (v0.5.0). Not built at v0.5.0: no casting, no measured results; the decision places the casting in 008 after the session registry and team config.

3. Why

• Judged by impression. Whether a team worked well, which agent did which kind of work well, whether a lab was worth what it cost: all three were answered, for the owner's own teams, from memory and from what the agents said about themselves.
• The facts existed. How long finished work waited, how often a review sent work back, which agent was stopped by its lab's limit and when: each was in a file or on a screen at some moment. Nothing kept them, and nothing put them side by side.
• Three reviews that found nothing, and one run that did. A fault in stopping an agent was read five times by one lab's agent and passed. A second lab found it on its first read. The same night a real run found two more that every review and every test had passed. Which check finds what, on the owner's own work, is a fact that was had and never written down.
• A day of waiting nobody measured. Finished work waited fifty minutes, then two hours, for one agent that was in a conversation. It is known because a person noticed. Nothing had counted it.
• Which lab for which work. Work was moved from one lab's agents to another's several times in two days, each time on an impression. Some moves were right; which ones, nobody can say.
• The founder's question. At the end of a day he asked what was left of each lab's allowance. The answer took an agent ten minutes and was partly a guess.

The starting point's first bullet (a team shaped by guess) and the sizing story (a team shaped by habit) moved to 008's chapter I with the project analysis (an owner decision). The stories above are the public audit's missing item 1, folded from RFC 004's "Where we start from" and §3, as its RFC 004 rows record.

4. What it costs, and what it does not cover

These are the costs of what is proposed, not of anything released. The Measurement side of RFC 004's costs, folded from the public audit's missing item 1; the two project-analysis costs (a first analysis of a project can be wrong and will be believed; reading a project sends that project to a lab) moved to 008's chapter I.

• Measuring changes what is measured. Agents told they are compared on how fast work is delivered will deliver fast. Counting how often work comes back from a check invites the one who checks to let it pass. Counting what was delivered invites an agent to take the easy work and leave the hard. Comparing labs on work that was not alike produces a ranking that means nothing and will be believed. What TeamCLI counts, a team will tend to produce. The text commits to measuring from what it saw; it cannot commit that what it saw is what mattered.
• Looking costs. Reading a team's whole day uses what is paid to a lab, sometimes more than the work it is meant to judge. A measurement says what it cost, and a small one comes first.
• It reads everything a team did. A measurement of a team reads what every agent did. It is the largest reader in a team and is subject to every limit the Kernel sets, with no exception.
• A project can try to steer its own analysis, and so can an agent that knows it is being measured. The first is material and is treated as such. The second is why commitment 7 exists, and it holds against a mistake more surely than against an attempt.
• More is kept, and not only by the owner. Findings about the owner's projects and about how each agent worked are files on the owner's machine: one more thing that exists and can be read (the Kernel). And the lab whose agent did the looking has read what it looked at; removing a finding does not reach there.
• Numbers about agents are not numbers about people, and TeamCLI does not measure the people who work with a team.
• It does not replace looking. A finding tells the owner where to look. It does not tell them that the work is good.

What this release must not pretend

What exists at v0.5.0 does not amount to measurement: usage readings with their provenance, the watch's observations, the team log. Nothing compares agents or labs, times work or waiting, rolls cost up the hierarchy, times a channel or feeds a casting. The rules of chapter B are commitments to build, not claims on the released code.

5. What would change our mind

The Measurement side of RFC 004's reversal criteria, folded from the public audit's missing item 2; the first criterion (teams proposed from an analysis no better than habit) moved to 008's chapter I.

• Findings nobody reads. Then the measurement must become three lines at the moment a decision is taken, or go.
• Teams that get worse at the work while getting better at what is counted. Then commitment 2 is doing harm, and less should be measured.
• Labs or trackers that already give these facts. Then TeamCLI should read theirs and keep only what it adds: the same facts for every lab, side by side.

6. What is true today

Today is v0.5.0 (52db9b75). Row 1 of the outline's table moved to 008's chapter I with commitment 1; rows 2 to 10 are the outline's, re-read and kept; rows 11 to 14 are new and say what the row says: not built at v0.5.0 beyond team usage. The per-stage absence behind row 13 was checked at the tag on 2026-10-19: no per-stage timestamps in the code.

#	Commitment heading	Today at v0.5.0
2	A team's work	State, log and usage observations exist; no delivery/queue timing analysis or pull history. src/labels/state.ts, src/log.ts, src/tasks/lease.ts; analytical proof none yet.
3	Each agent and lab on this work	Usage windows and provenance exist; no performance comparison or cost attribution. src/information/usage.ts; proof test/usage-quota.test.ts for readings only.
4	Team shape	Watch observes idle states and implements the idle thresholds an owner decision resolved and once-per-idle-period owner escalation (src/watch/checks/idle.ts:7–10,30–37, team-idle.ts), while team-shape analysis is not built; analytical proof none yet.
5	Plan versus actual	No estimate; plan display marks overdue dates. src/commands/plan.ts, src/tasks/adapter.ts; proof test/plan.test.ts.
6	Sourced findings	Usage reports source and age; general finding/correction record unbuilt. src/information/quota.ts; proof test/usage-quota.test.ts for readings only.
7	Observed measures	Ranked state sources (blocking conditions first; recent trace overriding an idle hook/screen/herdr word) and observed quota figures exist; broader work measurement unbuilt. src/labels/state.ts, src/information/quota-observe.ts; proof test/seat-state.test.ts, test/usage-quota.test.ts.
8	Says, does not decide	No analysis decision engine; check repair remains its separate explicit act. src/commands/check.ts; proof test/check-repair.test.ts for repair only.
9	Who looks and what is kept	Usage has a restricted/full caller view; machine figures omit team, seat, path and screen text. No general analysis-source/retention setting. src/commands/usage.ts, src/information/machine-readings.ts; proof test/usage-machine-readings.test.ts.
10	Settings	No analysis-policy family exists. src/policy/types.ts; proof none yet.
11	The session registry	Not built at v0.5.0 beyond team usage's readings; no session records written, the interim kept by hand (an owner decision). Proof none yet.
12	Cost by entity, project, team, seat and agent	Not built at v0.5.0 beyond team usage, tokens only (an owner decision); no roll-up views, no per-turn cost. src/information/usage.ts for readings only; proof none for the roll-ups.
13	Channel latency and failures	Not built at v0.5.0: no per-stage timestamps kept, no failure-rate counts. Proof none yet.
14	A cast's results fed back	Not built at v0.5.0: no casting, no measured results. Proof none yet.

Original §3. What exists today, as far as checked texts say it

Not the earlier table (that is above); what the Runtime text, the command pages at the integration tip and the owner's decisions establish, kept as the historical evidence inventory. Its older thresholds and source date are not the tag's current defaults; the current state/readings registry and Runtime spec own those details.

• team init writes a skeleton or restores the last approved copy; it reads nothing of the project (the command page).
• team usage reads every team's approval store on the machine, each team's accounts and windows, what is left and used, when each figure was last read and from which source; anyone may run it, it only reads; figures come from recorded screen readings or configured checks, never from seat counts; tokens only by decision (an owner decision), with availability as a separate command, proposed and not built.
• The watch logs the machine's readings every ten minutes and reports an idle seat, an idle team, unsent text and a figure past its limit (Runtime commitments 14 and 20).
• The registry keeps one record per agent with provenance; its cost view, a record outliving membership, is planned (Runtime commitment 3; an owner decision).
• The team log keeps one line per change with its time, rotated; the message history likewise (Runtime commitment 26); a take leaves no line (008 commitment 14).
• The round's timings and the daily report are 010's commitment 18, not built; the cost of checking is 005's commitment 8, not built; the gate scripts print their durations and selections (005 draft 1, commitment 8).

7. The security boundary

The right to read and containment stay with Kernel §§3, 9, 11, 12 and 14. Source material commands nothing; findings change no reserved object. What a lab may analyse remains bounded by its visibility; owner-controlled readable/removable records do not imply same-user containment. The session records of commitment 11 are the registry's, under the usual grants, and the cost figures of commitment 12 carry their source, measured or estimated. No stronger boundary is claimed.

8. Where it sits, and what it leaves to others

The fourth module stands alone as Measurement (an owner decision): the subjects of chapter A, the four rules of chapter B — which 005, 008 and 010 cite instead of restating — the settings of chapter C and the inputs of chapter D. The project analysis lives in 008's chapter I since the same decision. The Runtime keeps the registry, state, log, session records and reading records; 008 keeps task estimates, deadlines, the budget and the casting; 005 owns the source and cost of checks; 002 keeps the channel records whose latency and failure rates commitment 13 measures; 010 presents the round timings and the daily report.

9. Prior art and alternatives

The merge question RFC 004's reviewers asked (its question 7) is settled by an owner decision: 004 stands, renamed Measurement, keeping the statistics and the four rules; the project analysis moved to 008's chapter I. The three readings the outline weighed, kept as the record of the choice:

• Merged into 005. Findings and analysis as one reading of the same records: a check's finding and a measurement differ in what was asked, not in how they are kept. Rejected: the agent and lab comparison (commitment 3) is not about checks.
• Merged into 010's report. The daily report (010 commitment 18) as where the figures of commitments 2, 4 and 5 would be read. Rejected: the same comparison, and the rules of chapter B, which 010 would then have to state for its report.
• Stands alone, narrowed — the decision's. The module keeps what no other text has a subject for, and the rules every reader of the records follows. An owner decision chose this reading and moved the one subject that was not this module's (the project before a team) to 008.

10. Open questions

1. The merge — settled. An owner decision settles it: 004 stands as Measurement, the project analysis is 008's chapter I. This draft carries the settlement out (commitment 1 moved, §9 reconciled); the round records it.

2. The right to look, in the Kernel's words. RFC 004 says analysing is a right of its own, by default the owner's. The Kernel names no such capability and §13 lets no module add one. Is the reading a measurement does the same read every seat's scope bounds (§9, §12), so that "who looks" is "which seat, within its scope", with no new word?

3. The report's home. 010 commitment 18's daily report, 005 commitment 8's cost of checking, and this module's commitments 2 and 4 describe one page. Decide who defines its columns and who reads it.

4. For the build: What is kept, and where. The usage readings live in the owner's configuration folder; the log and the state beside the team file; a finding nowhere. Decide the first finding record (shared with 005's §10 question 2) and its retention.

5. Comparability. RFC 004's question 5 stands: "on your work" against work that was not alike. Commitment 3 now says what "not comparable" is computed from — what each was given to do; whether that is enough to make the comparison fair is the round's.

6. RFC 004's open points 2, 3, 4 and 6 (what "well" is; how much must be recorded to keep commitment 7; a finding that starts a proposal; who receives a finding in a team of one or with nobody leading), unanswered by any decision so far. Point 1 (how the owner is asked the first time) moved to 008's chapter I with the project analysis, on the public audit's row.

7. Round-1 proposals on the right to look. Is the existing Kernel read sufficient, as round-1 reviews propose?

8. Round-1 proposals for the remaining questions. Should the report divide metric definitions, check columns, and container/cadence/assembly among 004, 005 and 010, with owner and lead as default readers (§10.3)? Should a shared finding record live under the project's .agents/, with id, kind, source, observation time/observer, subject, facts or estimate, status and correction trace, retained for 90 days by default (§10.4)? Should comparability require matching role, work kind and check bar, a minimum sample, and display N, model/version/effort, rework and cost without a scalar ranking (§10.5)? These are round-1 proposals; one asks to keep those questions open and names the missing task field or derivation for comparability. For §10.6, should “well” use delivery/check outcomes, active/wait time, quota stops and cost per delivered task, with independent check and owner/lead acceptance? Are structured session, task, check, message-stage and quota records sufficient without full transcripts or raw project contents? Should findings go to the owner when no lead exists, with the sole seat reading within its scope? These round-1 proposals remain questions: one leaves the existing proposal-default rule unchanged, and another asks to retain the four source questions until a decision is recorded.

12. Links to the spec

No new spec is lifted from this text. Its formats are other texts':

• Specs-registry §3.7 (the session record, planned at v0.5.0; an owner decision) is the format commitment 11 reads; this text adds no field to it.
• Specs-budgets §7.3 — the cost accounting by entity, project, team, seat and agent, its sources, views and staged plan (commitments 3 and 12).
• Specs-seat-state-and-watch — the watch's checks and readings, the typed lines (commitments 4, 6, 7).
• Specs-tasks-and-broker — the task and lease records (commitments 2, 5, 14).
• Specs-messaging — the envelope's per-stage timestamps whose latency and failure rates commitment 13 measures (002's).
• Specs-registry — the agent, team and project records commitment 12 rolls cost up along.