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
105 lines
5.4 KiB
Markdown
105 lines
5.4 KiB
Markdown
# 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.
|