Luigit
repositories / termux-janitor

termux-janitor

Interactive cleanup assistant for Termux: transparent, safe, confirmed disk reclamation.

owned by admin

tools/spec-engine/spec/DIAGNOSTICS.md

Raw
Rendered preview

Diagnostic catalog

Codes are stable and greppable. TJSP-E* codes are engine-owned. TJSP-P* codes are profile-owned and defined by the consuming repository.

Every diagnostic prints the same shape:

CODE: what is inconsistent

kind:    what kind of fact
owner:   canonical owner of the fact
inspect: command that shows the fact
         command that shows its dependents
resolve: the permitted resolution
verify:  the command that proves the fix

Subject codes

A subject code classifies the owner of the disputed fact. One code covers every structural failure about that kind of fact; the message line states the specific inconsistency.

Code Kind Owner
TJSP-E010 document catalog documents registry
TJSP-E020 concept concepts registry
TJSP-E110 requirement requirements registry
TJSP-E210 test specification test registry
TJSP-E220 prose fixture fixture root
TJSP-E240 executable binding binding registry
TJSP-E310 verification obligation verification registry
TJSP-E250 executable product test test registry
TJSP-E251 unregistered fixture implementation binding registry
TJSP-E400 implementation unit implementation registry
TJSP-E420 unregistered implementation source implementation registry
TJSP-E500 generated projection generated output
TJSP-E600 repository path repository layout

Drift and lifecycle codes

These describe a specific failure rather than a class, and carry additional fields.

Code Meaning
TJSP-E120 stale requirement reference; dependent names a superseded revision
TJSP-E230 reviewed prose fixture changed without synchronization
TJSP-E260 reviewed binding source changed without synchronization
TJSP-E320 stale verification-obligation reference
TJSP-E410 reviewed implementation source changed without synchronization

Rules

SE-DIAG-03. A code, once published, keeps its meaning. Narrowing a code requires a new code.

SE-DIAG-04. A fingerprint diagnostic states both classification branches: presentation-only changes keep the revision and record the new digest; semantic changes increment the owning revision and migrate every dependent link.

SE-DIAG-05. A diagnostic an author cannot act on without external documentation is a defect. Fix the message, add an inspection command, or add a generator.

zig build spec-tool -- status is an inspection reference for structural graph failures when current verification progress can guide resolution.

# Diagnostic catalog

Codes are stable and greppable. `TJSP-E*` codes are engine-owned. `TJSP-P*` codes are profile-owned
and defined by the consuming repository.

Every diagnostic prints the same shape:

```text
CODE: what is inconsistent

kind:    what kind of fact
owner:   canonical owner of the fact
inspect: command that shows the fact
         command that shows its dependents
resolve: the permitted resolution
verify:  the command that proves the fix
```

## Subject codes

A subject code classifies the owner of the disputed fact. One code covers every structural failure
about that kind of fact; the message line states the specific inconsistency.

| Code | Kind | Owner |
|---|---|---|
| `TJSP-E010` | document catalog | documents registry |
| `TJSP-E020` | concept | concepts registry |
| `TJSP-E110` | requirement | requirements registry |
| `TJSP-E210` | test specification | test registry |
| `TJSP-E220` | prose fixture | fixture root |
| `TJSP-E240` | executable binding | binding registry |
| `TJSP-E310` | verification obligation | verification registry |
| `TJSP-E250` | executable product test | test registry |
| `TJSP-E251` | unregistered fixture implementation | binding registry |
| `TJSP-E400` | implementation unit | implementation registry |
| `TJSP-E420` | unregistered implementation source | implementation registry |
| `TJSP-E500` | generated projection | generated output |
| `TJSP-E600` | repository path | repository layout |

## Drift and lifecycle codes

These describe a specific failure rather than a class, and carry additional fields.

| Code | Meaning |
|---|---|
| `TJSP-E120` | stale requirement reference; dependent names a superseded revision |
| `TJSP-E230` | reviewed prose fixture changed without synchronization |
| `TJSP-E260` | reviewed binding source changed without synchronization |
| `TJSP-E320` | stale verification-obligation reference |
| `TJSP-E410` | reviewed implementation source changed without synchronization |

## Rules

**SE-DIAG-03.** A code, once published, keeps its meaning. Narrowing a code requires a new code.

**SE-DIAG-04.** A fingerprint diagnostic states both classification branches: presentation-only
changes keep the revision and record the new digest; semantic changes increment the owning revision
and migrate every dependent link.

**SE-DIAG-05.** A diagnostic an author cannot act on without external documentation is a defect.
Fix the message, add an inspection command, or add a generator.

`zig build spec-tool -- status` is an inspection reference for structural graph failures when
current verification progress can guide resolution.