Commit Graph
172 Commits
Author SHA1 Message Date
istos b0b0927de6 board: 36 → in-progress (istos) 2026-07-31 16:10:10 +02:00
istos cedcfbfe3c board: 39 → in-progress (istos) 2026-07-31 16:05:57 +02:00
istos 8a6d5a6c78 board: 35 → done (istos) 2026-07-31 16:05:39 +02:00
istos 26e6bb333d site: point the landing page at the reader's problem, not the mechanics
The hero explained the architecture before saying why anyone would care:
'task files in stage directories', 'stdlib-only', 'narrates' are words
that mean something once you already use bench. Every line now maps to
something the audience has actually hit — agents outrunning the person
supposed to be tracking them.

- Hero: 'Run a team of coding agents. Stay in control.' The old headline
  keeps its job as the brand line, in the footer of every layout.
- A new section between hero and doors: three sentences a reader has
  said out loud, each answered by a mechanism rather than a promise.
  Deliberately unboxed — the doors below are the page's one grid of
  cards, and repeating that shape would make the eye work twice.
- The six doors lead with the outcome and keep one mechanism as the
  evidence for it, which is the inversion of what they did before.
- Title and description follow, since a pasted url is the same pitch in
  another form.

Two lines that were quietly false are fixed too: the strip's comment
still said this site counts nothing (Fathom counts pageviews now), and
'no per-seat pricing' would have tripped the fiction guard in
tests/test_site_landing.py, which forbids the word outright.
2026-07-31 16:04:03 +02:00
istos d5c999fa79 site: keep maintainers' notes out of the build
The host uploads the assets directory whole, so a .md left in static/
becomes a public url — static/fonts/README.md was live, telling readers
how to refresh fonts they cannot write to. copy_static skips it, and
internal_targets skips it too: the link checker and the copier have to
agree, or a link to a skipped file would pass the build and 404 on the
site. The licences are .txt and still ship, which is the point of
committing them.

Card 43 records the other thing today's run turned up: the suite reads
the developer's own local/.env, so two sync tests fail here and pass in
CI.
2026-07-31 15:56:02 +02:00
istos 662ecc001f site: add Fathom analytics, and fix the caching rule it sits beside
Two changes to what the live site sends.

Analytics: Fathom's tag goes in every template's <head>, deferred. It is
cookieless and collects nothing about a person, so no consent banner —
but it is a third party, so the CSP names cdn.usefathom.com for script
and connect rather than opening the door generally, and the tests that
said 'no script at all' now say 'no script this site depends on, and no
origin nobody chose'.

Caching: the host concatenates a header two matching rules both set
rather than overriding, so /* and /static/* each setting Cache-Control
sent 'max-age=0, must-revalidate, max-age=31536000, immutable' on the
stylesheet — first max-age wins, and the year-long cache never happened.
Measured on the live site, which is where the from-memory assumption in
task 32 said to check it. Now /static/* is the only rule that sets it
and HTML takes the host's revalidating default; the post-deploy checks
in site/README.md verify both ends.
2026-07-31 15:39:46 +02:00
Ronald AshriandGitHub fbd273a6ae Merge pull request #31 from 12vectors/task/35-the-site-reads-on-a-phone
35 — Make the site read on a phone
2026-07-31 15:28:25 +02:00
istos db3b56b737 merge main into task/35: keep both rails' folded strips and 34's lede
article.html: 34 added the lede under the h1, 35 added the folded
contents strip in the same place. Both belong, and site.css settles the
order — its lede adjacency names .menu-contents + p, so the strip sits
between the title and the lede.

Two things the merge exposed rather than caused:

- $toc and $sidebar were spelled inside article.html's own comments,
  and string.Template substitutes there too, so every page carried a
  second copy of both rails inside a comment (28 toc links for 7
  headings). Doubled to $$toc / $$sidebar, as the template contract
  already said to.
- test_site_pages assumed one rendering of each rail. Both are now
  written twice by design, so the tests assert every rendering agrees
  with the page instead of assuming there is one.

The card file keeps main's location: the board owns a card's stage, and
main had already moved 35 to review/.
2026-07-31 15:27:00 +02:00
istos 5f11108d56 board: 41 → done (istos) 2026-07-31 15:16:14 +02:00
Ronald AshriandGitHub d04d665dff Merge pull request #30 from 12vectors/task/41-the-drawer-renders-wrapped-lists-as-lists
41 — The drawer renders a wrapped list item as one item
2026-07-31 15:16:05 +02:00
istos 51206b3dba board: 35 PR opened (istos) 2026-07-31 15:13:05 +02:00
istos e43afb8684 board: 41 PR opened (istos) 2026-07-31 15:13:02 +02:00
istos fbb3446009 site: carry the fonts' OFL texts beside them
Committing the woff2 files is redistribution, and OFL 1.1 asks that its
text and copyright notice travel with the font. IBMPlex.LICENSE.txt from
IBM/plex, ZillaSlab.LICENSE.txt from mozilla/zilla-slab; both ship in
dist/static/fonts/ with the faces they cover.
2026-07-31 15:11:32 +02:00
istos a15147a926 site: commit the seven woff2 files
Fetching them per checkout made every deploy machine ask Google for the
site's own typography, and a clean checkout build silently fell back to
system fonts. 113 KB, immutable under their filenames — which is what
the year-long immutable cache in root/_headers already assumes.
2026-07-31 15:09:02 +02:00
istos 85469537e5 tasks: five cards from this session's review of the board
37 sync resolves its remote like github.py does, and says so when it
cannot; 38 a card being merged wears the state and holds still; 39 the
tab says whether agents are working; 42 a long closing report keeps its
headline instead of its tail. 40 (the open-questions launch gate) is
archived, unmoved by the board and so never committed by one.
2026-07-31 15:06:19 +02:00
istos 6dcf6e4c1a site: keep fetched fonts and wrangler's cache out of git
site/fetch-fonts.py downloads the seven woff2 files once per checkout,
as site/README.md documents, so they are build inputs rather than
sources. .wrangler/ is the cache a deploy leaves behind.
2026-07-31 15:06:11 +02:00
istos 800cbc6429 board: 41 → review (istos) 2026-07-31 15:01:56 +02:00
istosandClaude Opus 5 d25221bb74 The drawer reads a wrapped list as one item
md() split a block into physical lines and made each one a unit. Task
files are hard-wrapped at ~74 columns, so the second line of an item
became its own bullet, `- [ ]` rendered as a literal bracket pair,
nested lists flattened, and prose kept the author's ragged edge as
<br>. "Enough for these task files" was exactly what it was not.

Lists are now grouped into logical items before rendering: a new item
begins only at a marker, and a line without one is continuation text
joined with a space. Indentation is honoured — a marker past its level
opens a nested list, a shallower one closes back to the level that
fits — and one entry point serves both bullets and ordered lists, so
an <ol> nests under a <ul> the same way. Task-list items render as a
glyph in a span, never an <input>: the file is the source of truth and
the drawer is not an editor. A ticked box reads as settled (--calm);
an open one stays neutral. Paragraphs and blockquotes join their
source lines with a space, so prose reflows to the drawer's width.

Fences, tables, headings and rules are untouched, including the fence
state machine that spans blocks.

The tests lift esc() and md() out of the page and run them under node,
because the renderer is a pure function and its output is what to
assert on; node is not a bench dependency, so those checks skip when
it is absent and source-level invariants cover the shape of the fix.
One check renders every card on the board plus AGENTS.md and asserts
one bullet per source marker — the acceptance criterion applied to the
whole corpus.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-31 15:01:26 +02:00
istos 4d60872625 board: 35 → review (istos) 2026-07-31 14:58:26 +02:00
istosandClaude Opus 5 33aebd90d6 site: make the docs read on a phone
The design is drawn at a fixed 1180px with three-column articles and a
two-column hero, and the site's first traffic is a link pasted into a
chat and opened on a handset. This is what happens below that width —
three max-width steps, and nothing that takes effect at or above the
width the design defines.

The two columns an article loses come back as <details> strips: "On
this page" folds under the title at 1080px, where the gutter goes, and
the section nav becomes a menu under the masthead at 760px, where the
sidebar goes. Both are filled from the same $sidebar and $toc as the
columns they replace, so a folded copy cannot say something the column
does not — and one menu that opens and closes needs no script, which
keeps the site's promise of shipping none.

The rest is what the acceptance asks for: a table becomes its own
scroller with an edge shadow that appears only while there is more to
the right; a token that cannot break, breaks; fenced code keeps
scrolling inside its own block; the hero and title steps come down
without leaving Zilla Slab; everything a finger has to hit is --tap
(44px) tall; and the masthead, footer and hero actions wrap instead of
widening the page.

The one thing that would have changed desktop is guarded rather than
noticed later: the contents strip is a sibling between the h1 and the
body's first paragraph even when display:none, so the lede rule names
it too.

tests/test_site_responsive.py mechanises all four promises, including
the one that matters most — every media query is a max-width below the
design.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-31 14:57:53 +02:00
istos b89e9c6ed4 board: 25 → backlog (istos) 2026-07-31 14:54:25 +02:00
istos e2c0738763 board: 41 → in-progress (istos) 2026-07-31 14:49:15 +02:00
istos 36b9f8c43d board: 35 → in-progress (istos) 2026-07-31 14:40:08 +02:00
istos 6204e1ad50 board: 34 → done (istos) 2026-07-31 14:40:08 +02:00
istos 016b28254d board: 35 → in-progress (istos) 2026-07-31 14:39:26 +02:00
istos 9bf20e8dd7 board: 34 → done (istos) 2026-07-31 14:39:17 +02:00
Ronald AshriandGitHub 1e1db9705c Merge pull request #29 from 12vectors/task/34-guides-and-concepts-from-agents-md
34 — Generate the guides and concept pages from AGENTS.md
2026-07-31 14:39:15 +02:00
istos c42e24253a board: 34 PR opened (istos) 2026-07-31 14:31:52 +02:00
istos 9b494a3f0e board: 34 → review (istos) 2026-07-31 14:31:44 +02:00
istosandClaude Opus 5 7ab45f49fd site: the guides and concept pages, in the 1a Harbour layout
Fills the middle of the site. Nine routes, every body a heading slice of
AGENTS.md or README.md, and the article layout given the furniture the
design calls for.

The manifest gains the two concepts nothing covered: /concepts/task-files/
(the header format, from AGENTS.md's own section) and /concepts/adapters/
(the adapter summary, which is the other half of the three-layer law).
/concepts/stages/ now runs through "Moving a task", because the five
directories and moving between them are one idea.

The layout:

- A lede under the title — the one sentence an article authors, taken
  from the manifest's `description` or an explicit `lede` where the two
  want different words. A slice starts mid-document; a reader arriving
  from the nav is owed a line saying what they are looking at.
- Prev/next at the foot, walking the sidebar's own order so the arrows
  and the rail cannot disagree. Pages with no section (the landing page,
  the 404) are not on the flow.
- "Edit this page on GitHub" anchors to the section the page was cut
  from, built from the same `from` heading the slice starts at.

Two bugs the new pages found:

- string.Template substitutes inside HTML comments, so a comment naming
  the body placeholder emitted the whole body twice and closed itself
  early on the first `-->` in it.
- Promotion could produce a second <h1>. A slice that deliberately runs
  past its own section carries headings at the `from` level, and those
  promoted to h1 on a page that already had one. Promotion now stops at
  h2, where they read as peers — which is what putting them on one page
  said in the first place.

tests/test_site_pages.py covers the furniture on the real built site:
the routes, the layout, the sidebar marking one page, the contents list
being exactly the body's own h2s in order, the prev/next chain end to
end, the edit link's anchor, the six landing-page doors, and a table, a
fenced block and a nested list surviving the renderer. The scratch-repo
helper now copies every file a slice links to, since the builder checks
those exist.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-31 14:29:49 +02:00
istosandClaude Opus 5 5ac3547821 docs: fix the sections the site cuts its pages from
The site's page bodies are heading slices of these two files, so a
sentence that only makes sense to an agent inside an installed project
becomes a sentence on bench.12vectors.com. Fixed at the source rather
than forked into the site:

- "The flow is linear" and its diagram sat at the end of "Pull requests",
  which put the whole stage flow on the PR page and left "Stages" with no
  opening. Moved under "## Stages", where it introduces what follows.
- "Agents working the board" ended in a stray sentence about worktrees
  and one-agent-per-task; folded into the start-work paragraph it
  belongs to.
- Start work no longer claims to launch `claude -p`: it launches through
  the configured adapter, which is the whole point of adapters.
- "see below" and "the PR guard above" name their sections instead,
  since above and below are other pages on the site.
- The tool-chips sentence had grown into the middle of the verdict it
  interrupted ("The card wears it in the design system's colours", with
  no nearby "it"). Split into two paragraphs.
- "Task file format" gains a table of every header field, what it may
  contain and who writes it — including PR, which the board writes and
  nothing documented until now.
- Paths are written from the repo root, the reference-directory example
  no longer names another project's regulator, and README's three-layer
  law links the two documents it points at rather than naming them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-31 14:29:36 +02:00
istos f15d7bd3e9 board: 36 → to-do (istos) 2026-07-31 14:11:24 +02:00
istos 8695b859b3 board: 35 → to-do (istos) 2026-07-31 14:11:21 +02:00
istos 93f36e6e26 board: 34 → in-progress (istos) 2026-07-31 14:11:19 +02:00
istos 29c6dc1dd1 board: 33 → done (istos) 2026-07-31 14:11:19 +02:00
Ronald AshriandGitHub 60c2be8949 Merge pull request #28 from 12vectors/task/33-the-docs-landing-page
33 — Build the landing page: Dockside, on things bench really does
2026-07-31 14:11:11 +02:00
istos 59012ec7fa board: 33 PR opened (istos) 2026-07-31 14:11:01 +02:00
istos 165fc0e40b board: 33 → review (istos) 2026-07-31 12:10:57 +02:00
istosandClaude Opus 5 274ad6b2c6 site: the landing page, on things bench really does
Turn design 1b (Dockside) into `/`: a terminal hero, the claim README.md
already makes, six doors, and a strip at the foot. The layout is task
31's; what this commit is really about is that nothing factual on the
page is typed by hand.

- **Two facts are read, not written.** `site/build.py` reads the install
  one-liner out of README.md's "Install into a repo" block and the
  version out of `manager/core/VERSION`, and offers them to the template
  as `$install_block` and `$version`. A renamed section, a missing
  VERSION or an install section that lost its command block stops the
  build, exactly as a renamed heading already did. `pages.json` loses
  its `version` key, and a build refuses one if it comes back.

- **A dead internal link stops the build.** Every href a rendered page
  emits — a door as much as a link inside a slice — must resolve to a
  route in the manifest or a file in `static/`/`root/`. The check runs
  after rendering and before writing, so a bad link leaves the last good
  build standing rather than shipping a 404 with a nice typeface.

- **Six real doors.** `pages.json` grows the routes they open: install
  and first run, the five stages, agents on the board, PRs and review,
  team mode, the three-layer law. They are heading slices, i.e. the
  stub routes task 33 expected and task 34 will re-cut.

- **The terminal is a transcript.** README.md's own command, then lines
  install.py and board.py really print, with the abridgement declared in
  the terminal's title bar. `tests/test_site_landing.py` holds every one
  of those lines against the source that prints it, so a reworded prompt
  fails the suite instead of quietly making the page fiction.

- **No fake telemetry.** Turn 1's "most opened this week" strip becomes
  the version, read from VERSION, and a link to the releases.

The landing page no longer carries a generated body, so the tests that
read one from it now read `/concepts/stages/`, and the two scratch repos
in the suite copy VERSION alongside the markdown.

python3 -m unittest: 407 tests, OK.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-31 12:10:25 +02:00
istos 68ee681c18 board: 33 → in-progress (istos) 2026-07-31 11:51:50 +02:00
istos bca3f3055e board: 32 → done (istos) 2026-07-31 11:51:49 +02:00
Ronald AshriandGitHub 80c58195ee Merge pull request #27 from 12vectors/task/32-serve-bench-12vectors-com-from-a-worker
32 — Serve bench.12vectors.com from a Cloudflare Worker
2026-07-31 11:51:41 +02:00
istos 25b55d5734 board: 32 PR opened (istos) 2026-07-31 11:49:17 +02:00
istos 0ff6457cae board: 32 → review (istos) 2026-07-31 11:49:09 +02:00
istosandClaude Opus 5 6c06583109 site: serve bench.12vectors.com from a Cloudflare Worker
site/wrangler.jsonc puts site/dist/ behind bench.12vectors.com as static
assets. No `main`: the site is files, and a Worker with no script is the
cheapest correct way to serve them.

  html_handling      force-trailing-slash, so /x redirects to /x/ — the
                     url the pages link and rel=canonical names. One
                     page, one address; no url ends in .html.
  not_found_handling 404-page, so an unknown path gets dist/404.html
                     with a 404 status rather than the landing page
                     with a 200.
  routes             bench.12vectors.com as a custom domain. Cloudflare
                     takes the hostname at the zone level and makes the
                     DNS record; nothing else on 12vectors.com moves.

site/root/_headers carries the response policy. HTML revalidates on
every view, so a deploy is visible on the next reload without anyone
clearing a cache; /static/* is kept for a year and never re-checked,
which is safe because the stylesheet and icon urls carry a hash of their
contents. The general rule is written first and the specific one second,
so a host that merged the two instead of overriding would still land on
max-age=0 — the safe side. Alongside it the baseline a public page owes:
nosniff, a referrer policy, a year of HSTS without preload,
X-Frame-Options, and a default-src 'none' CSP that makes "no analytics,
no third-party anything" something the browser enforces rather than
something a test asserted once.

Deploys are run by hand, as releases already are — no Cloudflare token
in repository secrets, no first deploy pipeline. site/README.md names
the account, the Worker, the route and the four-command sequence, plus
the four things to check after a deploy that no test here can reach.

The tests cover everything before Cloudflare: that the config says what
the site needs, that the build writes the files it names, and that
wrangler.jsonc, pages.json and README.md cannot drift apart about which
domain this is. A live response is not among them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-31 11:47:12 +02:00
istosandClaude Opus 5 ad639a33d3 site: a 404 page, a root/ tree, and stamped asset urls
Three things the build owed the host before the site could have an
address, all of them visible in site/dist/ rather than in a deploy
script.

A 404 page. Cloudflare's not-found handling serves a literal 404.html
from the root of the assets directory, so a route may now name an .html
file instead of ending in "/" — the one that does is /404.html, a normal
manifest entry with its own layout. It is the site's design and the
site's nav, with a way back to the landing page, a noindex and no
canonical. A null section keeps it off the nav it renders.

site/root/, copied verbatim to the TOP of the build the way static/ is
copied to a subdirectory of it. _headers is what it holds; the host
reads that file from the root and nowhere else. A file in root/ that a
route would also write stops the build rather than letting one silently
win.

Stamped urls for the stylesheet and the icon: the templates link them
through $stylesheet and $icon, which carry a ?v=<hash> of the file's own
contents. Nothing in static/ is renamed, so the tree and the /static/*
glob stay as they were — but the url changes when the file does, which
is what will make a year-long immutable cache safe.

Tests ask the builder where a route lands rather than keeping their own
copy of the rule.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-31 11:46:56 +02:00
istos 6828bd8c19 board: 32 → in-progress (istos) 2026-07-31 11:34:06 +02:00
istos a36242e4fe board: 31 → done (istos) 2026-07-31 11:33:32 +02:00
Ronald AshriandGitHub 6088035356 Merge pull request #26 from 12vectors/task/31-minisite-skeleton-and-build
31 — Stand up site/ and generate its pages from the repo's own markdown
2026-07-31 11:33:25 +02:00
istos 1b5cd1495f board: 31 PR opened (istos) 2026-07-31 11:32:34 +02:00