Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

docs: record integrated freshness correction and verification boundary

David Zhang4a2f71959cab
diff --git a/specs/jevgrep/README.md b/specs/jevgrep/README.md
index 6a4e8c0..867cdca 100644
--- a/specs/jevgrep/README.md
+++ b/specs/jevgrep/README.md
@@ -12,15 +12,14 @@ its frozen artifact: eight baseline solves preserved, eight cost wins, 33.21%
lower total Sol cost. [Confirmation evidence](assets/work-clock-confirmation.md)
owns all ten results and their limits. No paid benchmark or grader remains active.
-Next: integrate the filesystem-freshness fixes being implemented in the isolated
-`codex/final-freshness` worktree. Final independent review found buffered navigation
-source uploaded after ignore changes and stale non-Python excerpts returned after
-role evaluation. Required final freshness checks and per-network-attempt validation
-must fix those cases without changing healthy spike requests or output. Run their
-red/green installed tests and healthy parity, then determine what remains necessary
-to validate the corrected artifact. Do not transfer the frozen cohort's measured
-results to changed code without evidence. The pre-fix full default gate passed;
-its green result did not cover these newly reproduced cases.
+Next: finish serial merged verification and no-call preparation, then validate
+and run the separate `installed-jg-freshness-v1` cohort against saved baselines. The freshness
+correction is integrated in `92ca7f9`; its isolated worktree is removed. Exact
+archive checks passed on macOS and both Linux architectures. The first full gate
+had one five-second timeout under concurrent platform testing; no test allowance
+was changed. [Freshness evidence](assets/source-freshness.md) owns the corrected
+archive identity, failure reproductions and verification status. Do not transfer
+the previous cohort's measured results to the corrected archive.
Preserve healthy retrieval semantics and the canonical skill while fixing
filesystem freshness. Keep the measured archive immutable; it matches the
@@ -42,7 +41,7 @@ Evidence and boundaries:
[presentation trial](assets/presentation-study.md): rejected experiments,
source-parity probes and limits on causal explanations.
-Priority: validate and integrate the freshness correction without weakening
+Priority: validate the integrated freshness correction without weakening
acceptance; resolve the whole-product review; consolidate choices against the
final code; then close-spec. Slice 08 remains open. No publication or
release tag is authorized for the intentional `0.0.0` development checkpoint.
diff --git a/specs/jevgrep/assets/source-freshness.md b/specs/jevgrep/assets/source-freshness.md
new file mode 100644
index 0000000..f4395c4
--- /dev/null
+++ b/specs/jevgrep/assets/source-freshness.md
@@ -0,0 +1,50 @@
+# Source freshness at deferred boundaries
+
+The final review reproduced two gaps: queued navigation could upload buffered
+content after an ignore change, and a non-Python file changed during role
+evaluation could retain stale excerpts. Earlier green checks did not cover those
+boundaries. The correction is committed in `92ca7f9`.
+
+Retrieval now binds request inputs to their source snapshots without adding that
+metadata to Jev's payload. It checks eligibility and content before evaluation,
+again before each provider attempt after any retry delay, and before returning
+the final result. The existing filesystem reader remains the policy owner.
+Source invalidation removes stale evidence and marks discovery incomplete.
+
+Two details preserve useful behavior. Preflight reads become ready in FIFO order,
+so adding asynchronous validation does not reorder healthy requests. When a
+buffered group contains an invalid donor, finite splitting retains healthy
+siblings rather than discarding the entire group. Neither changes healthy
+prompts, thresholds, source budgets, skill text or rendering.
+
+This is revalidation, not a filesystem lock. Sequential checks cannot prevent a
+file changing afterward, and already transmitted requests cannot be recalled.
+The guarantee is that detected changes are not knowingly reused at subsequent
+validation boundaries.
+
+## Evidence and candidate identity
+
+The new real-filesystem/HTTP regressions cover queued requests, provider retries,
+relationship and cross-file donors, healthy siblings and final output. The packed
+CLI also exercises queued uploads and final invalidation. Pre-fix reproductions
+and corrected results are retained under `/tmp/jg-freshness-*-red*.log` and
+`/tmp/jg-freshness-*-green.log`; the maintained tests are in
+`test/retrieval-freshness.test.ts` and `test/installed.test.mjs`.
+
+The corrected frozen archive is
+`/tmp/jg-freshness-candidate/dzhng-jevgrep-0.0.0.tgz`, SHA-256
+`4589072fc0ff44257599dddda8bc5807c9c5515bbe1dcaedfe729645d9c4622c`.
+Its native macOS arm64 smoke passed two cases. Both Linux arm64 and amd64 passed
+all seven selected installed cases, including source freshness and Python assets.
+Logs: `/tmp/jg-freshness-native.log` and
+`/tmp/jg-freshness-frozen-{arm64,amd64}.log`.
+
+The first merged default verification passed 109 tests but timed out one existing
+donor test at five seconds while both platform checks ran concurrently. This is
+not a passing full gate. The serial rerun passed that donor test in 0.51 seconds
+and all 110 Bun tests. The remaining full verification is running, with evidence
+in `/tmp/jg-freshness-merged-verify-serial.log`; no test allowance was changed.
+
+The accepted work-clock cohort measured the preceding archive. A separate frozen
+ten-task treatment cohort must validate this corrected executable; saved baselines
+remain immutable and earlier treatment cells cannot be pooled into its result.
diff --git a/specs/jevgrep/choices.md b/specs/jevgrep/choices.md
index 7047933..9d4d7aa 100644
--- a/specs/jevgrep/choices.md
+++ b/specs/jevgrep/choices.md
@@ -221,6 +221,21 @@ Gap: artifact layout and execution mechanics were delegated. Reach: results from
different candidates cannot be pooled into acceptance; failed attempts and unknown
bills remain visible. Verdict: sound. Confidence: high.
+### Recheck source when deferred work is ready to use it
+
+When: final source-freshness correction. A queued request may wait while the user
+edits or ignores a file. Bind its content to an in-memory snapshot, then use the
+same filesystem policy to check that snapshot before evaluation, provider retries
+and final output. Keep this bookkeeping out of Jev's input. A detected change
+removes stale evidence and makes the result incomplete.
+
+Gap: source freshness was required, but the deferred validation boundaries were
+not fully specified. Reach: these checks are observations, not locks; changes
+after a check remain possible. Validation readiness preserves request order, and
+splitting invalid groups preserves their healthy siblings. This adds filesystem
+reads without changing the healthy retrieval policy. Verdict: sound. Confidence:
+high for detected-change handling; no claim of atomic filesystem consistency.
+
### Reuse installed command journeys for native macOS verification
When: supported-runtime verification. Install a tarball into a temporary npm