Skip to content

Extend verification from chain integrity to the conditions the model can already detect #6

Description

@schickling-assistant

Problem

compass verify today reports three things: files that were rejected at admission, orphans whose parent has not arrived, and a frontier that will not evaluate. Those are all chain and storage conditions — whether the catalog is intact and readable. compass status adds a per-Plan line with head count, a diverged flag, and convergence.

The model defines a second family of conditions that neither command reports, and that a reader has no way to discover except by already suspecting them:

Condition Where it is required Reported by
Steps stranded permanently unsatisfiable by a retirement CMP.DM-R05b nothing
A criterion no record can ever match CMP.DM-R13d the write path only, at the moment one record is written
Open divergence, distinguished from settled CMP.DM-R05a status as a boolean; show in prose; not as a problem

CMP.DM-R05b is the sharpest of the three, because it states its own timing requirement and that requirement is currently unmet: a stranded dependent "must be visible at the moment of retirement rather than discovered later through readiness that never advances." Today it is discovered exactly the way the requirement says it must not be — by watching readiness fail to move, with CMP.DM-R15 faithfully explaining that the Step is waiting on a dependency, forever, in wording indistinguishable from work that is simply not done yet.

Open divergence is a milder version of the same shape. status says diverged: true, which is a fact about the lineage; CMP.DM-R05a is about whether that divergence is open — "only open divergence may prompt action" — and a boolean that stays true forever after any historical disagreement is precisely the always-on report that requirement warns will be ignored.

Proposal

Extend verify's problem set from chain integrity to the union of both families, keeping its existing shape — a list of typed problems, an exit code, and the same fields for a human and a program. Concretely, add:

  • stranded dependents, computed at head: Steps whose dependency chain includes a retired Step, which can therefore never become ready. Ideally also surfaced at the moment the retirement is committed, which is what CMP.DM-R05b actually asks for;
  • open divergence as a problem with its two sides' authors and Rationales, since CMP.DM-R07 records the author precisely because "reconciling divergence requires knowing who wrote each side" — and suppressed once settled;
  • criteria that can never match, to the extent the existing write-time check can be re-run as a read.

And order the output by what it asks of the reader rather than by which layer produced it:

  1. Cannot be read — rejected, unresolved, evaluation stopped. Nothing below it can be trusted. CMP.CLI-R14 already distinguishes exactly these because "the operator's next action differs in each case — look elsewhere, wait, or stop trusting the Plan."
  2. Needs a decision — open divergence. The repair is authorship.
  3. Structurally stuck — stranded dependents, unsatisfiable criteria. The repair is a revision.
  4. Possibly incomplete — orphans, convergence unknown, replication inactive. The repair is waiting.
  5. Nothing outstanding — which verify already does well (ok everything verifies), and which matters: a report that only speaks when unhappy has a silence indistinguishable from not having run.

Two points from a predecessor in-house planning design worth carrying over:

  • Problems before inventory. Human-facing output leads with what needs a decision, what is stuck, and what is stale, and puts the full work list last. A report that opens with a table of every Step buries the one line that mattered under the ninety that did not.
  • Everything mentioned is addressable. Each row names the exact thing — which version, which Step, which criterion — so a reader can act on it, or hand it to someone else, without a translation step. verify's existing plan/kind/subject/reason shape already does this and the model-level rows should keep it.

Fit with the contract

  • This adds no semantics, which is what CMP.CLI-R01 requires: every condition listed is already defined in the model, and the command renders them. It is a composition gap, not a second authority.
  • CMP.CLI-R02 is already satisfied by verify and stays satisfied.
  • It remains a pure read, so the separation 04-cli/spec.md insists on between verification and repair is untouched — the point that "collapsing them into one command with a flag would make the irreversible operation one keystroke from the safe one" applies with more force as verify grows, not less.
  • Worth deciding: whether model-level problems share verify's non-zero exit code. A stranded dependent is a real defect; an open divergence is a normal state that happens to need a person, and CMP.CLI-R04 warns that rendering divergence as an error "would teach operators to treat it as breakage." They may want different severities under one report.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions