The lead reported being unable to reach the reckon server on 2026-08-21. The service
was in fact healthy — reckon.service active, lingering enabled, listening on
127.0.0.1:8765, and serving browser requests minutes earlier. The connection
failure itself was a client-side tunnel, not the server. But probing the server to prove
that turned up a real defect underneath: the discovery endpoint takes seconds to
tens of seconds per call, which on a laggy forwarded port is indistinguishable
from a dead server.
This plan carries two halves of one complaint about the served surface. The first is
mechanical and fully diagnosed: discovery is slow, and for three projects it is slow on
every single request because the cache that exists never fires. The second is
editorial: the server knows considerably more than the SPA puts on screen, and some of
what it does put on screen is stale or unexplained. A surface that answers in 16 seconds
and then under-explains what it shows is failing at both ends of the same job.
§2 — Discovery latency landed
Landed 2026-08-21. Repeat discovery now answers in 6–15 ms for every
mounted project, against a 100 ms target: nova 5.39 s → 0.012 s (449×), imas-codex 4.15 s →
0.006 s (692×), imas-ambix 2.36 s → 0.012 s (197×). The boolean cache veto is deleted and
replaced by per-dependency external signatures; the git creation map is cached against
repository HEAD with incremental range refresh; git failures now log distinctly instead of
being swallowed. Commit 5922bcf, merged cb16b49, 5 new tests,
suite 1,950 passed / 0 failed.
Open negative result: the cold-scan criterion of under 3 s is NOT met —
imas-efit still takes 14.8 s on the first call after a server restart. This follows directly
from the locked git-creation-source decision declining disk persistence. The
criterion and the decision were authored in the same session and disagree. Resolution is the
lead's call: persist the map to disk, or restate the criterion as steady-state.
Full detail: execution record.
§3 — What the SPA communicates
The second half of the complaint is editorial rather than mechanical, and it is deliberately
scoped as an audit first. The SPA is mature — a four-tab shell, cockpit, inline dependency
graph, command palette, status menus, north-star rollups, a live crew watcher — spread over
roughly 4,500 lines of JSX across eleven components. Guessing at improvements across a
surface that size would produce churn, not clarity. So this section dispatches a legibility
audit whose output is a ranked, evidence-backed finding list, and only then acts on it.
Three defects are already confirmed by direct inspection and are in scope regardless of what
the audit adds:
The SPA tells users to edit a path that is no longer canonical.docs/ui/home.jsx instructs, twice and in user-visible copy, to
edit ~/docs-server/mounts.json. The canonical location has been
~/.config/reckon/mounts.json since the XDG move;
~/docs-server/ is a legacy fallback only. A user following the on-screen
instruction edits a file the server may not read.
Latency is invisible, so a slow surface reads as a broken one. This is the
thread connecting both halves of this plan. The SPA gives no indication that a discovery
scan is in progress or how stale the data on screen is — which is exactly why a 16-second
response was reported as a failure to connect.
Project state that disagrees with itself is displayed without comment.docs/state/reckon/index.json still lists sprints S3–S6 with
active_sprint_id: "S5", while the live distributed sprint resources under
docs/sprints/ run to S11 with S9 active. Discovery composes the correct
answer, but the stale legacy block remains readable and nothing flags the divergence.
Deliverables
Legibility audit. A ranked finding list over every SPA surface, each
finding naming the file, the specific information defect, the reader it fails, and a
concrete remedy. The audit must distinguish three classes: information the server already
holds but the SPA does not show; information shown but unexplained or ambiguous; and
information shown that is stale or wrong. Findings must be evidence-backed against the
real served payloads, not speculative redesign.
Correct the three confirmed defects above, plus whatever the audit ranks
as high-value and low-risk.
No redesign. This section improves what is communicated, not the visual
language. A proposal to restructure navigation or restyle the shell is a separate plan and
belongs in a followup, not here.
Done when
The audit exists as a research resource with ranked findings; the three confirmed defects are
fixed; every remaining accepted finding is either landed or carried as an explicit followup
with its rank and rationale; and the SPA renders correctly against a live server with no
console errors.
§4 — Out of scope
The reported connection failure itself. The service was healthy throughout — active,
lingering, listening, and serving. The forwarded port from the lead's laptop is client-side
and is handled by imas-codex tunnel; nothing in this plan changes it. It is
recorded here only because it is what surfaced the latency defect.
Visual redesign of the SPA, new navigation structure, and any change to the plan schema or
the MCP tool surface.
§ Decisions
How should a document's creation date be sourced once the full-history walk is removed from the request path?
The current call recovers true first-commit time but costs 89% of a cold scan. The alternatives trade accuracy for latency differently, and the choice determines whether the "created" column stays trustworthy.
Keeps the creation dates accurate, which drop-git-use-ctime would silently degrade: a fresh clone or a rsync gives every file the same ctime, so the created column would become meaningless exactly where history is most useful. Keying on HEAD is sound because a file's first-commit timestamp is immutable and history only grows at the tip, so an unchanged HEAD provably needs no requery. Disk persistence was not taken now because it optimises the server-restart path only, and restarts are rare next to the per-request cost this plan is removing; it stays available as a followup if cold-start after restart proves painful.
Should a cold discovery scan be allowed to block the request, or should the endpoint serve a stale-but-immediate result and refresh behind it?
Even with both root causes fixed, the first scan of a 898-document repository costs real time. Serving stale-then-refreshing removes the worst-case wait entirely but introduces a window where the SPA shows data it knows is out of date — which interacts directly with the §3 finding that staleness is currently invisible.
Once the cache actually holds, a cold scan is rare rather than routine, so stale-while-revalidate would add a permanent correctness caveat to every read in exchange for removing a rare wait. Serving data the server knows is out of date is a poor trade for a planning surface whose whole purpose is telling the truth about project state, and it would interact badly with the finding that staleness is currently invisible. The reader-facing remedy belongs in the SPA showing that a scan is running, not in the endpoint answering with data it distrusts.
§ Followups
Execute the plan — discovery latency then the SPA legibility audit
§2 is fully diagnosed and ready to dispatch. §3 begins with an audit node whose ranked
findings gate the fixes that follow it, so §3 implementation waits on that output.
The two sections touch disjoint files and can start concurrently.
/reckon-ship surface-latency-and-legibility
Landed across nine worker nodes on codex, all worktree-isolated. §2 complete: repeat discovery 5.39s → 0.012s on nova (449×), 692× on imas-codex, 197× on imas-ambix, every mounted project now under 40ms against a 100ms target; the boolean cache veto deleted in favour of per-dependency external signatures; the git creation map keyed on HEAD with incremental range refresh; git failures logged rather than swallowed. §3 audit published with 15 ranked findings, of which 6 are fixed including both criticals — the ready-gate rejection branch, honest write acknowledgement, the misleading sprint drag affordance, sprint item rationale and contract, crew project identity, and the resolved config path. Two pre-existing suite failures unrelated to this plan were repaired rather than walked past: repository detection now requires a real repository instead of any ancestor holding a .git entry, and the skill contract assertions were reconciled with roster-authority vocabulary while compacting the document to 11,631 tokens under its unchanged 12,000 bound. Suite 1,951 passed / 0 failed; all eleven worktrees removed after verifying reachability. Two items remain open and are carried in the next followup: the unmet cold-scan criterion, which contradicts a decision locked in the same session, and audit ranks 3, 6, 9-15.
Resolve the cold-scan contradiction, then land audit ranks 3, 6 and 9-15
Two distinct pieces of work remain, and the first needs a lead decision before it can be dispatched.
The cold-scan criterion is unmet and contradicts a locked decision. §2 targets a cold scan under 3 seconds; imas-efit still takes 14.8 s and nova 7.1 s on the first call after a server restart, because the locked git-creation-source decision declined disk persistence on the reasoning that restarts are rare. Both were authored in the same session and disagree. Either persist the creation map under the config home so a restart no longer re-pays the history walk — reopening that decision through the dissent flow — or restate the criterion as a steady-state target. Do not quietly amend the criterion to match the outcome.
Audit rank 3 has a live data half the SPA half cannot fix. S5 and S9 are both marked active while the legacy index names S5 as focus; S5 has 7 of 8 items shipped with only registered-repo-state-migration outstanding, while all current work sits in S9. The SPA remedy is to show every active sprint and warn on the conflict rather than silently picking one. Whether S5 should close is a sprint decision for the lead, not a rendering fix.
Remaining findings. Rank 6 renders authored-versus-effective status with its open-gate count on compact surfaces. Ranks 9 to 15 are medium and low: plan-fetch provenance when a partial document would otherwise look complete, discarded resource-version tokens, graph-tab reading order, crew phase legibility, handoff prompt copying, vocabulary explanation, and blocker ownership. Full detail with source files and remedies is in the audit research resource.