# Observed Development-Cycle Lessons

This document records self-validated lessons from the active development cycle.
They are examples of the contracts above, not additional authority.

## 1. A label is not a guarantee of delivery

Observed failure: evidence marked `full` still retained a head/tail extract.

Lesson: tests must inspect the actual model-visible body, not only metadata.
The behavioral contract is “the sentinel source text reaches the next parent
request,” not “the evidence object says `fidelity=full`.”

## 2. Partial evidence cannot become an action gate

Observed failure: a partial branch extract generated cross-file requirements,
then blocked a legitimate edit before the edit tool ran.

Lesson: extraction coverage is advisory. It can identify an evidence gap, but
must not replace the edit tool's exact-match/hash result with a synthetic
admission failure.

## 3. Cache reuse requires source visibility, not only identity

Observed failure: a path/hash cache said an identical file had been read while
the parent model only saw a pointer or branch wrapper.

Lesson: cache admission needs all of path, current source version, requested
range coverage, and exact-body visibility. If any is absent, execute the read
or return the actual canonical body; never return a rejection masquerading as
success.

## 4. Tool feedback is more valuable than controller choreography

Observed failure: controller preflights denied reads and edits, creating
recovery loops with no new filesystem evidence.

Lesson: for normal operation, let the model invoke the tool and see natural
results. Preserve real atomic protections in the tool implementation and keep
runtime guidance observational.

## 5. Static source assertions are weak behavioral proof

Observed failure: source-string tests continued to assert legacy blocking
language even after behavior had been deliberately changed.

Lesson: use source inspection only for narrow wiring assertions. The primary
regression harness should exercise model request, tool dispatch, evidence
retention, mutation, and verification in sequence.

## 6. Update correctness is process identity, not installation success

Observed failure: a new CLI package was installed while an old root-owned
daemon continued serving the shared port.

Lesson: verify immutable boot identity, attest service ownership before a
handoff, preserve same-version active runs, and supervise service-owned child
processes after package replacement.

## 7. A verification layer should reveal truth without becoming a gate

The desired development frame is:

```text
Claim -> observable -> check -> exact evidence -> stale/valid state
```

It should make missing proof visible to the model and operator, attach a pass
or failure to the right claim, and invalidate only relevant evidence after a
mutation. It must not force an old plan, block exploration, or convert missing
proof into a fictitious tool failure.