The defects your agents measured
Defects about the system itself are written down as files carrying the measurement that found them, checked against a fixed shape, and counted by class — and repair stays a human decision.
An agent doing your work meets the system it is working in. It meets a check that cannot fail, a refusal that names the wrong thing, a document that contradicts another document, a step that takes four minutes because something upstream is wrong. Those are defects, and whoever met one is the only party that holds the reading.
So it is written down — not as a note in a transcript nobody reads, and not as a ticket written later from memory, but as a file with the measurement in it.
A defect is one file, with the measurement in it
Each defect is one Markdown file in the development/backlog/bugs/ directory of your workspace's
record. The file is written by whoever met the defect — an agent or a person; nothing in the
product assigns the duty to a particular role. Closed defects are kept beside it rather than
deleted.
The difference between that and a ticket written afterwards is the difference between a reading and a conclusion. A ticket written later says "the capacity check is unreliable." A defect file says "here is the command I ran, here is what it printed, here is what I expected." The first is an opinion you have to adjudicate. The second you can re-run — which means anyone can disagree with it on the evidence, including the agent that wrote it.
What a defect file must carry:
| Part | Shape |
|---|---|
| A title | the file's first-level heading |
| The measurement | a second-level heading containing the word measurement (or measured), with what was run and what it printed beneath it |
| The cost | a second-level heading containing the word cost: the time or the work the defect consumed |
| The class | a top-level bullet - class: <id>, one id from the closed set below |
A defect with no measurement and no cost fails the check
The shape is checked by a command, not at the moment the file is written.
judges one file and exits 2 when it fails, naming each rule it missed —
doc-defect-measurement-missing, doc-defect-cost-missing, doc-defect-class-missing or
doc-defect-class-unknown — and prints the smallest file that would pass. Two further findings
are warnings only: a measurement that does not look reproducible, and a defect that does not name
its cause apart from its symptom. The family must be named: --family auto never recognises a
defect file, because any titled Markdown document would match.
reads every *.md in one directory and prints one row per file — including the files that
fail, each with the rules it missed. It is a report and exits 0 even when every file fails; it
does not descend into subdirectories. Both verbs are in the command reference.
⚠ Nothing stops a file being written without a measurement or a cost. The refusal is the
check's verdict; a workflow that never runs the check never meets it. Put
saphan doc check --family defect wherever defect files are accepted into your record if you
want the rule to hold there.
⚠ The check reads headings, not meaning. A heading that says measurement over three lines of recollection passes. What the check guarantees is that the place for the evidence exists, not that what is in it can be re-run.
The queue counts only what a record backs
The queue is grouped by class — what kind of defect this is. The classes are a closed set:
| Class | Name | What it covers |
|---|---|---|
L | law / canon | a rule that is missing, contradictory, or not applied |
O | orchestration | the shape of the work: what is serial, what one head keeps in its head, the owner's acts |
H | hooks / guards / skills | a guard that fires wrong, is illegible, or is absent where prose failed |
V | vendor mechanics | the agent CLI's own behaviour: sandbox, session, output |
E-gap | engine missing | a capability the engine lacks: a verb, a flag, a view, a notice |
E-bug | engine defect | the engine does something wrong or slowly |
P | practice | the method of whoever directs the work: probes, reading instruments, order shape |
D | owner decision | a trade only the owner may make |
The counts above the queue are derived from the rows, never typed. A defect whose class cannot be
derived is counted as unclassified, and says why — no row for it, a conflicting row, an empty
class, or a class outside the set. It is not guessed into the nearest class to make the totals look
complete, and it is not left out to make them look clean.
⛔ A number that no row supports does not appear. A cell whose source is missing reads
absent with the reason beside it, never 0 and never an estimate.
⚠ On the console today, every defect counts as unclassified. The queue takes a defect's class
from a separate classing record, not from the file's own - class: bullet, and that record is not
connected to the console yet. For the same reason the cost, in-flight and age columns read
absent. The Bug Harvester screen shows the real file counts; its
per-class split is not yet usable.
Repair is your decision, and never automatic
Nothing here repairs itself. A defect being written down, checked and counted is a defect described; turning it into a change is a separate decision and it is yours.
The queue shows three switches:
| Switch | Position |
|---|---|
| harvest | always on — defects are read and counted; nothing can turn this off, and it spends nothing |
| mandate | your written decision about repair: which classes are admitted, a cap on what repairing may cost, and whether a repair is reviewed before it lands. Nothing is defaulted; a mandate missing any of the three is refused |
| send | off, and it cannot be turned on — see below |
⚠ The mandate is built and not in use. The product can read and validate one, but nothing reads it during work: there is no configuration key or file location for it, no class is admitted by it, and nothing stops at its cap. What that means for you today is simpler than the table: no repair is ever started for you. The console's start button on this queue is a rehearsal that describes a dry run; it dispatches nothing. Repair happens when a person orders it, through the ordinary review gate, on the same terms as any other change.
⚠ Nothing leaves unless you send it — and today you cannot. The defects stay in your record.
Sending them anywhere — an issue tracker, a support channel, us — is designed and not built: the
send switch is fixed off and disabled on screen, there is no export path and no integration that
forwards a defect, so there is nothing to turn off and nothing configured wrongly that could leak
one. What is therefore not proven is the shape of any such export, including what it would redact.
What this does not tell you
The limits close the page, because they are the part that decides whether the rest of it is useful to you.
| it does not tell you | why |
|---|---|
| that the queue is complete | It holds the defect files somebody wrote. A defect nothing ran into, or nobody wrote down, is not in it, and no count here is evidence about the defects nobody met. |
| that a class is the right class | A class is a filer's choice from a closed set, which makes it checkable, not correct. The unclassified count is honest about the cases it could not derive; it is not a claim that the derived ones are all well-named. |
| that a file's measurement can be re-run | The check confirms the measurement section exists, not that the command in it still reproduces. |
| how long a defect has been true | A file is written when the defect was met. That is usually later, sometimes much later, than the moment it became true — and the console's age column is not connected yet. |
| what a repair will cost | There is no cost estimate, and the mandate's cap is not enforced by anything today. |
| anything about defects in your own software | This is the system's record of itself — the fleet, its checks, its documents, its refusals. The defects in the code your agents are writing live in your repository and your tests, where they belong. |
Where to look next: the Development screens are where the queue is
shown, and saphan doc is the check and the census.