@jimhoyd/urlcode 0.4.0-alpha.1 → 0.4.0-alpha.3

package/docs/{NEXT-STEPS.md → archive/2026-09-19/NEXT-STEPS.md}

@@ -1,10 +1,20 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
 # Next steps: closing the gaps
 
 Status: plan written 2026-09-18 from the cleanup, the
 [usability review](USABILITY-REVIEW.md) and the AI-first framework brief.
 Each item says what it fixes, where the work is, how it is proven, and its
 size (S: a day, M: a week, L: more). Phases can overlap; order inside a phase
-is the recommended sequence. The [roadmap](../ROADMAP.md) owns what ships;
+is the recommended sequence. The [roadmap](ROADMAP.md) owns what ships;
 this page owns how the gaps close.
 
 ## The rule everything below serves
@@ -16,7 +26,7 @@ policies, admin patterns and deployment glue on every project, and the person
 ends up owning it. URLCode's job is a small, deterministic, portable vocabulary
 in readable YAML, so generated code goes to the part that is the application.
 The agent describes what; the runtime owns how. The three tests that decide
-what gets built are in [project direction](PROJECT-DIRECTION.md#why-your-ai-should-build-your-application-not-your-framework):
+what gets built are in [project direction](../../PROJECT-DIRECTION.md#why-your-ai-should-build-your-application-not-your-framework):
 the boundary test (do agents generate this across unrelated projects?), the
 feature test (does it reduce what the agent must know, generate, debug or
 maintain?) and the evidence test (measured repetition, not a feature list).
@@ -24,14 +34,41 @@ maintain?) and the evidence test (measured repetition, not a feature list).
 The order below follows from that. **Prove the thesis before building on
 it.** Phase 0 is the benchmark; if it shows a large saving, the rest is worth
 the work, and if it shows a small one, the abstraction is not doing enough yet
-and the next phases change. Nothing here weakens the security model: guest
-code stays untrusted, grants stay operator-owned, agents cannot self-authorize,
-unsupported behavior fails with the route named, and inspection tooling never
-becomes a privilege escalation path.
+and the next phases change. Nothing here weakens the security model: a
+`sandbox: true` route's isolation stays exactly as strict, grants stay
+operator-owned regardless of a route's trust setting, agents cannot
+self-authorize, unsupported behavior fails with the route named, and
+inspection tooling never becomes a privilege escalation path.
+
+**Status 2026-09-19 (sequence).** Most of Phases 1, 3 and 4 landed before the
+Phase 0 benchmark produced a single model-backed run. The instrument is built
+and tested (`benchmarks/agent/harness.ts`, `benchmarks/agent/count-lines.ts`,
+`benchmarks/agent/adapters/anthropic.ts`), but `benchmarks/agent/runs/` holds
+only `baseline.json`, a stub record, so the application-specific code ratio is
+still unmeasured and the re-prioritization 0.1 describes has never been
+exercised. This is an observation about the order the work happened in, not a
+change of priorities: Phase 0 still owns the evidence, and Phase 5 is still how
+each shipped phase gets measured. Items below are marked from the source at this
+revision.
 
 ## Phase 0: prove the thesis (M, core `benchmarks/agent/`, before anything else)
 
-### 0.1 The agent benchmark
+### 0.1 The agent benchmark — partly done
+
+Done 2026-09-19, the instrument only: the runner, the counting rule, the tasks
+and the storage format exist and are tested — `benchmarks/agent/harness.ts`
+(`runArm`, `summarize`, `securityChecklist`, `writeRun`),
+`benchmarks/agent/count-lines.ts` (`classify`, `codeRatio`),
+`benchmarks/agent/adapters.ts` (`selectAdapter`, `stubAdapter`) with
+`benchmarks/agent/adapters/anthropic.ts`, ten task directories under
+`benchmarks/agent/tasks/`, both arm preambles under `benchmarks/agent/prompts/`,
+`npm run benchmark:agent`, and `test/agent-benchmark.test.ts` ("the counting
+rule: functions and declared modules are the idea, everything else is
+plumbing"). The measurement is not done: `benchmarks/agent/runs/` holds only
+`baseline.json`, whose `model` is `stub`, and `benchmarks/agent/README.md`
+states that no number there is evidence until a stored run with a real model
+adapter backs it. Running the tasks in both arms against a real model, storing
+the runs and publishing only what they support remains the work below.
 
 Fixes: there is no evidence that URLCode saves agent effort, and the whole
 plan depends on it.
@@ -61,7 +98,16 @@ plan depends on it.
   too small or too hard to discover, and Phases 1, 3 and 4 are re-prioritized
   from what the runs show the agent still had to write.
 
-### 0.2 Authoring regression evals (S, once 0.1 exists)
+### 0.2 Authoring regression evals (S, once 0.1 exists) — done
+
+Done 2026-09-19: the five prompts are `benchmarks/agent/evals/*.yaml`
+(`add-redirect`, `add-authenticated-endpoint`, `serve-directory`,
+`add-middleware`, `create-webhook-endpoint`), scored against the eight criteria
+by `scoreEval` and `summarizeEvals` in `benchmarks/agent/harness.ts`, gated
+against `benchmarks/agent/runs/baseline.json` by `benchmarks/agent/gate.ts`, and
+run weekly by `.github/workflows/evals.yml`. Caveat: the committed baseline is a
+stub record and the scheduled job skips cleanly when no model key is configured,
+so the recorded pass rate proves the pipeline, not a model's behavior.
 
 Prompts for common requests ("add a redirect", "add an authenticated
 endpoint", "serve this directory", "add middleware", "create a webhook
@@ -80,7 +126,17 @@ read-side tools (`inspectProject`, `validateProject`, `explainRoute`,
 Keep all of it. The gap is that an agent still has to read documents to find
 facts the runtime already knows.
 
-### 1.1 Application-level `AGENTS.md` from `urlcode init` (S, core)
+### 1.1 Application-level `AGENTS.md` from `urlcode init` (S, core) — done
+
+Done 2026-09-19: `renderAgentsGuide` in `src/agents-guide.ts` generates the file
+from the installed capability catalog, `initProject` in `src/authoring.ts`
+writes it, and `initProjectWith` in `src/init-with.ts` calls `initProject`, so
+`init --with` writes it into the project directory too; `renderMcpConfig` writes
+`.mcp.json` beside it. `test/cli.test.ts` asserts the commands, the packaged
+skill path and the MCP tool names the file lists, its length bound, and that the
+committed `starters/default/AGENTS.md` equals what `init` generates from this
+runtime. Caveat: the public `urlcode-template` copy is outside this repository
+and is not checked here; `npm run check:downstream-skills` stays advisory.
 
 Fixes: a project made with URLCode is not self-describing to Claude Code,
 Codex or any repository-aware agent. Today's `AGENTS.md` explains how to work
@@ -97,14 +153,22 @@ on the runtime, not on an application.
 - Proof: starter test asserts the file exists and lists the commands; the
   public `urlcode-template` gets the same file.
 
-### 1.2 `llms-full.txt` and clean Markdown for the docs site (S, core; S, urlcode-docs)
+### 1.2 `llms-full.txt` and clean Markdown for the docs site (S, core; S, urlcode-docs) — partly done
+
+Done 2026-09-19, the core side: `scripts/build-llms-full.ts` generates
+`llms-full.txt` from 15 authoring documents in reading order with a table of
+contents and a token estimate in the file header, `npm run check` runs it with
+`--check`, and `test/llms-full.test.ts` covers determinism, rejection of a stale
+copy and the conservative link rewriting. The docs-site half is not done here:
+serving `/docs/<page>.md` beside `/docs/<page>` belongs to `urlcode-docs` and is
+not verifiable from this repository.
 
 Fixes: `llms.txt` must stay a compact index, but an agent that wants complete
 context has to fetch forty files.
 
 - Work: `scripts/build-llms-full.ts` concatenates the authoring documents
   (framework, AI authoring, YAML guide, field reference, specification,
-  routing, HTTP, middleware, assets, dynamic links, policies, extensions) in
+  routing, HTTP, middleware, assets, policies, extensions) in
   reading order with a table of contents; checked in `npm run check` for
   staleness like the field reference. The docs site serves `/docs/<page>.md`
   beside `/docs/<page>` so agents never parse HTML. Do not adopt `agents.txt`
@@ -112,7 +176,16 @@ context has to fetch forty files.
 - Proof: `npm run check` fails on a stale `llms-full.txt`; token estimate
   recorded in the file header.
 
-### 1.3 `urlcode context` with a token budget (M, core)
+### 1.3 `urlcode context` with a token budget (M, core) — done
+
+Done 2026-09-19: `urlcode context [--project] [--budget] [--json] [--stats]` in
+`src/cli.ts` over `buildContext`, `renderContext`, `estimateTokens` and
+`documentationTokens` in `src/context.ts`, derived from the compiled project and
+the capability catalog; `--stats` writes the estimate to stderr so stdout stays
+parseable. `test/context.test.ts` covers the cookbook and starter summaries,
+byte-identical output across runs, the fixed budget drop order with the estimate
+never exceeded, the CLI's YAML and JSON forms, and MCP `get_context`
+(`src/mcp.ts`) returning the same data read-only.
 
 Fixes: the central gap. An agent needs a handful of facts about this project
 and this runtime and spends tens of thousands of tokens reading documentation
@@ -136,7 +209,17 @@ to get them.
   same project yields byte-identical output twice; budget test that output
   never exceeds the estimate; MCP tool `get_context` returns the same data.
 
-### 1.4 Capability and schema fragment queries (M, core)
+### 1.4 Capability and schema fragment queries (M, core) — done
+
+Done 2026-09-19: `urlcode capabilities <name>` and `urlcode schema <path>` in
+`src/cli.ts` over `getCapability` in `src/capability-query.ts` and
+`getSchemaFragment`/`schemaPathNames` in `src/schema-query.ts`, both re-exported
+from `src/tooling.ts` and served as MCP `get_capability` and `get_schema`
+(`src/mcp.ts`). `test/capability-query.test.ts` asserts that every catalog name
+resolves with a valid, size-bounded fragment, that every schema path yields a
+valid inline fragment and an unknown path lists the valid names, that entries
+report bundled usage, grants and refusals from existing data, and that the CLI
+fails closed on unknown names.
 
 Fixes: `urlcode capabilities` reports target support per handler; an agent
 cannot ask "what does `throttle` accept, where does it run, which recipe
@@ -152,7 +235,15 @@ shows it" or "give me only the schema for `redirect`".
 - Proof: a test that every capability name resolves and every fragment is
   valid JSON Schema; a size test that no fragment exceeds a fixed byte cap.
 
-### 1.5 The URLCode agent skill (S, core `skills/urlcode/`)
+### 1.5 The URLCode agent skill (S, core `skills/urlcode/`) — done
+
+Done 2026-09-19: `skills/urlcode/SKILL.md` is 104 lines, ships in the package,
+and is named by the generated `AGENTS.md` through `skillPath` in
+`src/agents-guide.ts`; `test/cli.test.ts` asserts the reference and
+`test/release.test.ts` asserts the packaged starter copy. Caveat: the
+with-and-without comparison in the proof line waits on 0.1 — the URLCode arm
+preamble (`benchmarks/agent/prompts/urlcode.md`) assumes the skill, and no model
+run has been stored to compare against.
 
 Fixes: agents that support skills have no packaged instruction for URLCode.
 
@@ -170,7 +261,7 @@ Fixes: agents that support skills have no packaged instruction for URLCode.
 ### 2.1 Publish the three extension packages (decision, S) — done
 
 Done 2026-09-18: `@jimhoyd/urlcode-ui`, `-auth` and `-admin` are on npm as
-`0.1.0-alpha.1` against core `0.4.0-alpha.1`. The alpha caveat stays: source
+`0.1.0-alpha.x` against core `0.4.0-alpha.1`. The alpha caveat stays: source
 complete, independent review, deployment evidence and accessibility
 assessment pending ([issue 58](https://github.com/jimhoyd-com/urlcode/issues/58)).
 
@@ -198,9 +289,22 @@ Fixes: three disagreeing lists of verified peer commits (the CI workflows,
 - Work: `peers.json` in auth and admin; the workflows read it; the pack
   script defaults from it; `ACCEPTANCE.md` links to it. 2.1 has shipped, so
   the published versions (`@jimhoyd/urlcode@0.4.0-alpha.1`,
-  `@jimhoyd/urlcode-ui@0.1.0-alpha.1`) replace the SHAs and the file can go.
-
-### 2.3 `urlcode init --with auth,admin,ui` (M, core plus each extension)
+  `@jimhoyd/urlcode-ui@0.1.0-alpha.4`) replace the SHAs and the file can go.
+
+### 2.3 `urlcode init --with auth,admin,ui` (M, core plus each extension) — done
+
+Done 2026-09-19: `--with` is parsed in `src/cli.ts` and implemented by
+`parseWithNames`, `loadScaffold` and `initProjectWith` in `src/init-with.ts`,
+which resolves `@jimhoyd/urlcode-<name>` from the invoking directory, refuses a
+missing package or one without a `scaffold` export before writing anything,
+merges the fragments into the starter through a last include, and writes one
+`host.mjs` (`renderHost`), one `README.md` (`renderReadme`), `.mcp.json` and the
+`AGENTS.md` from 1.1, printing the `inspectExtensionRevision` digest for
+pinning. `test/init-with.test.ts` uses a fake `@jimhoyd/urlcode-<name>` package
+in a temporary `node_modules` and, when companion checkouts are present,
+composes the real auth and admin scaffolds. Caveat: each extension's own
+`scaffold` export and admin's clean-project acceptance live in those
+repositories and are not verified here.
 
 Fixes: three initializers with three directory conventions; no single command
 produces the layered project the framework page describes.
@@ -217,7 +321,20 @@ produces the layered project the framework page describes.
   `node_modules`; each extension tests that its `scaffold` output validates
   with core; admin's clean-project acceptance uses the new command.
 
-### 2.4 Print extension schemas: `urlcode extensions` (M, core)
+### 2.4 Print extension schemas: `urlcode extensions` (M, core) — partly done
+
+Done 2026-09-19, the command and the MCP tool: `urlcode extensions
+[--host-file] [--json]` in `src/cli.ts` over `describeExtensions` in
+`src/tooling.ts` prints each registration's name, version, targets,
+configuration schema, policy schema, mounts, policy routes and revision-pin
+verdict, and without a host file names the declared extensions and says schemas
+need one. The same function is exported from `src/index.ts` and served as MCP
+`get_extensions`, offered only when the operator started the server with a host
+file, which `test/extensions.test.ts` asserts against the
+`examples/extensions` registry. Not done: the fold-in. `urlcode context
+--host-file` reports host extension names and a plugin count rather than their
+schemas (`buildContext` in `src/context.ts`), and `urlcode capabilities auth`
+takes no host file, so registered contracts are not part of either view.
 
 Fixes: an agent cannot discover what `extensions.auth.config` accepts without
 reading auth's source; `urlcode mcp` cannot serve it.
@@ -231,7 +348,21 @@ reading auth's source; `urlcode mcp` cannot serve it.
 
 ## Phase 3: retrieval instead of reading (M each, core)
 
-### 3.1 Recipes as the vocabulary of common behavior
+### 3.1 Recipes as the vocabulary of common behavior — done
+
+Done 2026-09-19: every bundled recipe carries `recipe.yaml`, and the catalog is
+now ten — `authenticated-json-api`, `contact-form`, `cors-api`, `health-page`,
+`json-api`, `middleware`, `protected-download`, `static-plus-api`, `typescript`
+and `webhook-receiver` — which covers the seven this item names.
+`urlcode recipes search|show|add` runs through `src/ecosystem-cli.ts` over
+`searchRecipes` and `showRecipe` in `src/recipes.ts`, matching id, description,
+tags and capabilities locally with no service, and MCP gained `search_recipes`.
+`npm run check` validates the metadata and requires its derived fields to equal
+the capability preflight (`checkCatalog` and `derivedDifferences` in
+`scripts/check.ts`), and `test/recipes.test.ts` asserts a search hit per recipe
+and that every recipe validates, passes its fixtures and audits with its
+declared route count. Growing the catalog from the Phase 6 repetition log has
+not started; the current ten are the seed list above.
 
 Fixes: four bundled recipes with a README each and no metadata; an agent
 cannot search them, and nothing tells it to look before generating.
@@ -248,14 +379,33 @@ cannot search them, and nothing tells it to look before generating.
 - Proof: schema for `recipe.yaml` checked in `npm run check`; a search test
   per recipe; every recipe still validates, tests and audits.
 
-### 3.2 Examples become searchable the same way
+### 3.2 Examples become searchable the same way — done
+
+Done 2026-09-19: each example carries `example.yaml` in the recipe metadata
+shape, `urlcode examples search <text>` runs through `src/ecosystem-cli.ts` over
+`searchExamples` in `src/examples.ts` and names the smallest runnable match with
+its route, and the cookbook's per-route tags are generated into
+`examples/cookbook/route-index.json` by `scripts/build-cookbook-index.ts`,
+checked by `npm run check`. `scripts/check.ts` holds example metadata to the
+same preflight as recipes, and `test/recipes.test.ts` ("examples carry the same
+metadata shape and search returns the smallest runnable match with its route")
+is the search test.
 
 - Work: `examples/*/example.yaml` with the same metadata shape; `urlcode
   examples search <text>` returns the smallest matching runnable example and
   its route. The cookbook's forty routes get per-route tags in one index file.
 - Proof: search test; count audit unchanged.
 
-### 3.3 `urlcode explain` from compiled semantics
+### 3.3 `urlcode explain` from compiled semantics — done
+
+Done 2026-09-19: `urlcode explain [/route] [--json]` in `src/cli.ts` over
+`runExplainCommand` in `src/explain-cli.ts` and `explainRoute`/`explainProject`
+in `src/explain.ts`, derived from the compiled IR, including extension policy
+requirements when a host file is supplied. `test/explain.test.ts` covers the
+project table and route detail through the CLI, the sandbox boolean, the
+extension-protected route with a host registry, the nearest-route miss that
+never carries binding values, and that explain agrees with the runtime on
+methods and policies for every route.
 
 Fixes: `explainRoute` exists in the SDK and MCP; there is no CLI, and the
 output repeats matching rather than effective behavior.
@@ -268,7 +418,15 @@ output repeats matching rather than effective behavior.
 - Proof: snapshot tests on the cookbook; a test that `explain` and the
   runtime agree on methods and policies for every route.
 
-### 3.4 A generated semantic manifest
+### 3.4 A generated semantic manifest — done
+
+Done 2026-09-19: `urlcode manifest [--json]` shares the `src/explain-cli.ts`
+entry and runs `buildManifest` in `src/manifest.ts`; `build` writes
+`manifest.json` beside the artifact and MCP offers `get_manifest`.
+`test/manifest.test.ts` asserts determinism, that the revision equals the
+extension revision digest, that external requirements and recipe provenance are
+listed by name and never by value, and that the CLI prints the bytes the build
+writes.
 
 - Work: `urlcode manifest [--json]` (also written by `build` and offered by
   MCP as `get_manifest`) emits routes, capabilities, recipe provenance,
@@ -278,7 +436,17 @@ output repeats matching rather than effective behavior.
 - Proof: manifest equals `inspectProject` output for the same project;
   digest equals `inspectExtensionRevision`.
 
-### 3.5 MCP authoring layer, separately authorized (M, core)
+### 3.5 MCP authoring layer, separately authorized (M, core) — done
+
+Done 2026-09-19: `src/mcp-authoring.ts` adds `create_route`, `add_recipe` and
+`scaffold_feature` plus the `run_validate`, `run_test` and `run_audit` runners,
+enabled only by `--allow-authoring` on the operator's command line, which
+`src/cli.ts` refuses for any other command and which no tool argument or
+environment variable can set (`src/mcp.ts`). Every write is validated before it
+lands and returns the verdict. `test/mcp-authoring.test.ts` asserts the tools
+are absent without the flag, that absolute, parent, symlinked, dotenv, git and
+operator paths are refused, and that a create is followed by validation in one
+call.
 
 Fixes: MCP is read-only by design; an agent that wants to add a recipe or a
 route still has to write files by hand.
@@ -297,7 +465,20 @@ route still has to write files by hand.
 
 ## Phase 4: fewer lines for the common case (schema additions, `version: "1"` stays valid)
 
-### 4.1 Short form for function routes (M, core)
+### 4.1 Short form for function routes (M, core) — done
+
+Done 2026-09-19: `normalizeRoute` in `src/config.ts` expands
+`function: functions/x.mjs` into `{source, args}` with an argument per `{param}`
+and a required bounded path parameter for any the route does not declare itself
+(`SHORT_FORM_PATH_SCHEMA`), and a string `middleware` entry into `{source}`; the
+long form stays the IR. Both shapes are in
+`schemas/urlcode.schema.json` (`$defs.route.properties.function` and
+`.middleware`) and the generated field reference lists them as options.
+`test/config.test.ts` ("function and middleware short forms normalize to the
+long form the long form compiles to") asserts identical output, that a declared
+parameter keeps its schema, and that a bad short-form string is refused with the
+route named; the cookbook uses the short form in
+`examples/cookbook/routes/middleware.yaml`.
 
 Fixes: the smallest function route is ten lines.
 
@@ -308,11 +489,27 @@ Fixes: the smallest function route is ten lines.
 - Proof: generated reference updated; cookbook gains a short-form route with
   fixtures; a test that short and long forms compile to identical IR.
 
-### 4.2 Route-level `auth` as the semantic form (M, core plus auth)
+### 4.2 Route-level `auth` as the semantic form (M, core plus auth) — done
+
+Done 2026-09-19: the route-level `auth` key is in the schema
+(`$defs.route.properties.auth` over `$defs.routeAuth` in
+`schemas/urlcode.schema.json`) and expanded by `normalizeRouteAuth` in
+`src/config.ts`, which refuses a route that declares `auth` without an
+`extensions.auth` declaration, alongside `policies.extensions.auth`, or with
+`policies.extensions: false`; `required: false` documents intent and emits
+nothing. The type is documented in `src/types.ts`, and `test/recipes.test.ts`
+("the authenticated recipes use the auth short form and never let credentials
+reach the guest") covers both `auth: true` and a role requirement. The `cache`
+short form this item defers to later shipped with it:
+`$defs.route.properties.cache` and the cache branch of `normalizeRoute`, refused
+alongside `policies.cache`. Caveat: the auth repository's HTTP tests are outside
+this repository and were not run here.
 
 Fixes: protecting a route today is `policies: { extensions: { auth: {} } }`,
 which is the mechanism, not the intent. The form an agent should write is
-`auth: { required: true, roles: [admin] }`.
+`auth: { required: true, role: admin }`. (Delivered in `0.4.0-alpha.1` with
+`role` singular; `routeAuth` sets `additionalProperties: false`, so the plural
+`roles` this plan originally proposed is rejected by the validator.)
 
 - Work: a route-level `auth` key that expands to the `policies.extensions.auth`
   requirement the auth extension validates; `roles` maps to the extension's
@@ -365,7 +562,15 @@ whether links become a collection. Decide after review; build nothing first.
 `hiddenField`, `postForm`, `withDeadline` in the ui main entry; auth and
 admin drop their copies (`admin-markup.ts`, `admin-deadline.ts`).
 
-### 7.2 Auth and admin render through the kit (L)
+### 7.2 Auth and admin render through the kit (L) — partly done
+
+Done 2026-09-19, the core prerequisite only: the immutable-cache exception for
+hashed extension assets shipped. `ExtensionImmutableAssets` and
+`validateAssetPrefix` in `src/extensions.ts` bound a declared prefix to literal
+segments under the extension's mounts, and `immutableAssetResponse` is what
+lets such a response carry an asset cache-control instead of `no-store`. The
+rendering work itself is in the auth, admin and ui repositories and is not
+verified from here.
 
 Auth exports its catalogue and templates with view models, takes an optional
 `ui` from the host, and renders with `ui.kit.page` when present; admin the
@@ -388,28 +593,54 @@ walkthrough. Retire the `presentation` option one minor version later.
 ## Phase 9: hardening left from the audit (core, S each)
 
 - Direct tests for the sandbox pool, worker crash recovery and timeout kill
-  path (`src/functions.ts`, `src/function-worker.ts`, `src/guest-api.ts`).
-- Tests for `src/link-store-worker.ts` behind the WAL gate.
-- Re-verify the remaining line-number rows in `STANDARDS.md`; cite symbols.
-- Split the three longest reference documents (YAML guide, policies, dynamic
-  links) into task pages under 200 lines, so retrieval returns one page.
+  path (`src/functions.ts`, `src/function-worker.ts`, `src/guest-api.ts`) —
+  done 2026-09-19: `test/sandbox-pool.test.ts` covers load shedding with slot
+  reuse, parallel workers with per-slot heaps, the 250 ms-to-30 s respawn
+  backoff, the deadline kill with slot replacement, an abrupt worker exit
+  failing the in-flight invocation, startup failure and close, and the guest
+  `Request`/`Response`/context surface.
+- Re-verify the remaining line-number rows in `STANDARDS.md`; cite symbols —
+  done 2026-09-19: `docs/STANDARDS.md` records that every row was re-verified
+  at `8d7dd01` and now cites the implementing function or constant rather than
+  a line number, names the test that proves it, and says "unverified at
+  8d7dd01" where a row could not be re-checked; no line-number citation
+  remains in the file.
+- Split the longest reference documents (YAML guide, policies) into task pages
+  under 200 lines, so retrieval returns one page — done 2026-09-19:
+  `docs/yaml/` holds nine pages (largest `functions.md`, 160 lines) and
+  `docs/policies/` nine (largest `agents.md`, 182 lines), with
+  `docs/YAML-GUIDE.md` down to 57 lines. Caveat: `docs/POLICIES.md` is still
+  203 lines as the index page.
 - A pre-test check in the extension repos that fails fast with the SQLite
-  requirement named.
+  requirement named. Not verifiable from this repository.
 
 ## Sequence at a glance
 
+What remains, as of 2026-09-19:
+
 ```
-Phase 0  agent benchmark + code-ratio metric        (decides everything after it)
-Phase 1  AGENTS.md from init → llms-full → urlcode context → capability/schema queries → skill
-Phase 2  publish alphas → peers.json → init --with → extensions --schema
-Phase 3  recipe metadata + search → examples search → explain → manifest → MCP authoring
-Phase 4  short-form function route → route-level auth
-Phase 5  re-run the benchmark after each phase
-Phase 6  repetition log → collections spike, then decide
-Phase 7  shared helpers → kit adoption
+Phase 0  instrument built and tested; no model-backed run stored, so the
+         code-ratio evidence is still missing. Evals (0.2) run weekly.
+Phase 1  done: AGENTS.md from init, llms-full, urlcode context,
+         capability/schema queries, the skill
+         left: the docs site's /docs/<page>.md (urlcode-docs)
+Phase 2  done: published alphas, init --with, urlcode extensions + get_extensions
+         left: peers.json (auth, admin); extension schemas folded into
+         urlcode context and capabilities <name>
+Phase 3  done: recipe metadata + search, examples search, explain, manifest,
+         MCP authoring behind --allow-authoring
+Phase 4  done: short-form function and middleware routes, route-level auth,
+         the cache short form; 4.3 stays a standing rule for new fields
+Phase 5  waits on a Phase 0 run with a real model
+Phase 6  not started: no docs/REPETITION-LOG.md, no docs/SPIKE-COLLECTIONS.md
+Phase 7  extension repos; the core immutable-asset exception 7.2 needs is done
 Phase 8  proof gaps, in parallel, as people and environments allow
-Phase 9  hardening, in any gap
+Phase 9  done: sandbox pool tests, STANDARDS symbol citations, split reference
+         pages; left: the extension repos' SQLite pre-test check
 ```
 
 Phase 0 decides whether the rest is worth doing and in what order. Phases 1
 and 3 are what an agent meets first; the rest makes that cheaper or proves it.
+Because Phases 1, 3 and 4 landed ahead of the first model-backed run, that run
+now measures what shipped rather than choosing it; Phase 5's re-runs are where
+the choosing role returns.