3523dcf93e
plans/ held 58 documents and exactly one said whether it was open. The rest
mixed finished work, reviews of shipped work, parked specs and genuinely
pending ones, with nothing distinguishing them, so "how many plans are in
the queue" had no answer short of reading all 58.
Now `grep -H '^Status:' plans/*.md` is the answer:
50 done 3 in progress 2 planned 2 reference 1 parked
Statuses were derived rather than guessed: CLAUDE.md's own built list and
"What's NOT built yet" section, plus checking the subject exists in the
code. A review of work that shipped counts as done -- it records what was
found, it is not a request for anything. `reference` separates the two docs
that are conventions rather than work items (admin-design-standards,
admin-work-framework), which otherwise read as permanently-open plans.
The vocabulary is deliberately five words. A larger one invites "mostly
done" and "blocked-ish", which is how the directory became unreadable.
test_plans_declare_status.py keeps it from rotting: a new plan without a
marker fails, as does an unknown status, one buried below the eighth line,
or an open status with no reason -- "planned" alone is the state that rots,
since nobody can tell later whether it waits on a decision, a dependency,
or just nobody's turn.
Also updates the sweep plan with what landed and what did not, including
that #9 was not a defect.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VRQXz5SYZYVWscxS1QqF6U
5.4 KiB
Review: README restructure (commit 14a7653)
Status: done -- review of shipped work
What it was reviewing: opencode's implementation of
plans/readme-restructure.md — reshaping README.md around a
pitch → features → install → per-command usage structure borrowed from
supabase-plus's README shape. Checked the actual diff (git show 14a7653) line by line against the spec's explicit constraints, not just the
new document's surface quality.
Verdict: the restructuring itself is well done; one section's content was silently dropped, and one TOC link is dead
What's correct, including the part most likely to go wrong
The spec's two "needs a decision, don't invent" items — a ## License
section and a ## Repo & Contributions section — are both correctly
absent from the new README. Neither a LICENSE file nor an honest
contributions policy exists yet, and the plan was explicit that opencode
should not fabricate either. Checked directly (grep -i "license\|contribut" against every heading): nothing was invented. This
was the single most important constraint in the spec and it held.
Everything else structural matches: ## Features uses the five bullets the
plan proposed, pulled from existing claims rather than invented ones;
## Requirements is pulled out as its own section; ## Installation has
exactly the two real sub-methods (Local (venv), As a systemd service)
rather than fabricated ones; ## Usage is restructured into nine
per-command sections matching the plan's mapping table, and spot-checking
"Watch it live" and "Probe routing without spending" confirms the
Monitoring section's content (all five tools: /metrics, /events/decisions,
tui.py, baseline_report.py, router_cli.py) survived the reflow intact,
just condensed. A Table of Contents now exists where none did before.
## Setup's "Where Ollama lives" subsection was deleted, not moved
Confirmed by diff, not inference. git show 14a7653 -- README.md
shows this entire block removed with no corresponding addition anywhere in
the new document:
-### Where Ollama lives
-
-```bash
-ollama pull mistral-nemo:12b # or whatever you set as classifier.model
-```
-
-...To use one across a VPN, point **both** endpoints at it:
-...and apply `deploy/ollama-over-vpn.conf` on the serving host — Ollama binds
-`127.0.0.1` by default and will otherwise refuse. Bind it to the VPN address
-rather than `0.0.0.0`: Ollama has no authentication, so anything reaching the
-port can run inference and enumerate your models.
-
-Both endpoints move together because the verifier speaks Ollama's *native*
-API and cannot follow the classifier to a cloud provider...
Grepped the current README.md for ollama-over-vpn, ollama pull mistral-nemo, and Both endpoints move together — zero hits. This isn't a
paraphrase living somewhere else; the content is gone.
Why this matters more than an ordinary trim. This section carried a real
security instruction, not just background — Ollama has no authentication of
its own, and the doc's own words were the thing telling a reader to bind it
to a VPN address rather than 0.0.0.0. The plan's own "What must NOT
change" section was explicit: "Everything below stays exactly as it is,
moved but not rewritten" and "No new measurements, dates, or claims" —
the inverse, dropping an existing one, was never authorized either. The most
likely mechanical cause: the old "Setup" section's opening sentence moved to
## Requirements and its venv steps moved to ## Installation, and
"Where Ollama lives" — a ### subsection of the same old ## Setup — seems
to have been left behind in that split rather than carried to either
destination.
Dead TOC link: "Scheduled Jobs (systemd)"
The Table of Contents (line 74) still has an entry
- [Scheduled Jobs (systemd)](#scheduled-jobs-systemd). That heading no
longer exists — the content it pointed to was correctly moved into ### As a systemd service under Installation, which already has its own
correct TOC entry at line 43. The old line was never removed, so it's a
link to nowhere sitting in a document whose main improvement this pass was
adding working navigation. One line to delete.
A handful of other headings with em-dashes, backticks, or & (e.g.
`models` — one row per served model variant, Known Limitations & Open Items) produced anchor mismatches against a straightforward slugify check,
but GitHub- and Gitea-flavored anchor generation both have their own
non-obvious rules for those characters that a quick script can't be trusted
to reproduce exactly — these are worth a manual click-through in whatever
renderer this repo actually displays in (Gitea, at git.adlee.work), not
something to fix on the strength of this review alone.
Recommendation
Restore "Where Ollama lives" verbatim — it's sitting in git show 14a7653^:README.md (the pre-restructure version) if a clean copy is
needed — into ## Installation, most naturally as a third subsection
alongside Local (venv) and As a systemd service (it's setup guidance
that applies to either), or folded into Local (venv) if a separate
heading feels like too much for one paragraph plus a warning. Delete the
dead Scheduled Jobs (systemd) TOC line. Then do one manual pass clicking
every TOC link in the actual Gitea-rendered view, since that's the renderer
that matters here and not something worth guessing at from a script.