maintenance #

Maintenance is an improvement that survived its own falsification attempt: observed failure, a falsifiable cause, bounded evidence, an isolated candidate, and a verdict that says exactly what was and was not established.

the trail #

Start from an observation, not an idea. The observation carries the operation, the signature, and the error trace; the cause you propose has to be able to be wrong.

from klbr import maintenance

claim = maintenance.DiagnosticClaim(
    claim_id="c-1",
    category="import_error",
    description="klbr.skills is imported but not packaged",
    target_command="python -c 'import klbr.skills'",
)
evidence = await maintenance.load_maintenance_evidence(["event:412"])
assessment = maintenance.assess_diagnostic_claim(claim, evidence)
print(assessment.verdict, assessment.reason, assessment.missing_evidence)

load_maintenance_evidence is honest about what it could not resolve: unavailable references land in missing_evidence instead of becoming silent assumptions. An error trace that does not correlate with the claimed fault yields needs-evidence, not validation - an unrelated error does not confirm a diagnosis.

Author the candidate in an isolated workspace, so live source is never mutated in place:

from klbr import candidate

with candidate.CandidateWorkspace("/path/to/behavior") as isolated:
    isolated.write("klbr_hooks/delivery.py", new_body)
    print(isolated.diff())
    validated = isolated.validate()

The workspace refuses to be the live source, refuses to be its ancestor or descendant, and refuses to write through a symlink into it. assert_base_unmodified is what makes "I did not touch production" a checked claim.

verdicts #

The outcome vocabulary is the honest part. needs-evidence names what is missing. no-change says the evidence did not support a defect. candidate-failed is a result, not a failure to report. validated means the claim held against evidence. activated-under-observation means it is live and still being watched. observed-benefit-with-support is the only outcome that claims an improvement, and it needs a receipt. deferred-with-trigger and reopened say the problem is waiting and is back.

refusals #

A plausible retrospective claim does not get adopted for being plausible. Missing scope evidence produces needs-evidence. A rule proposed from a broad diagnosis is rejected when the commands that actually ran were permitted targeted ones.