Skip to content

83 files carry a Spec: specs/03-dsl.md trailer for a file that has never existed #106

Description

@debuggingfuture

Surfaced while reviewing #98. The agentic reviewer asked that PR to update specs/03-dsl.md § browser after browser.newPage was deleted. That file does not exist.

specs/ contains four files, all ADRs:

specs/adr/README.md
specs/adr/0001-cloudflare-workflows-scope.md
specs/adr/0002-memory-capability.md
specs/adr/0003-no-context-relay.md

git log --all -- specs/03-dsl.md is empty, and the path is not gitignored — it has never been committed on any branch. Meanwhile 83 source files carry a Spec: specs/03-dsl.md § … trailer, plus more pointing at specs/pm/plan.md (also absent).

Two things this costs:

  1. Every "the spec is the source of truth" trailer is unresolvable. A reader following one — or a reviewer asking for the spec to be updated alongside a code change, as happened on fix(runtime-cf): delete browser.newPage — the last dying stub in a live Layer #98 — hits nothing, and the request cannot be actioned.
  2. Reviews will keep generating this finding. It is correct in principle every time a capability's surface changes, and unfixable every time.

Worth deciding which way to close it: write the specs the trailers promise, repoint them at whatever is now authoritative (the ADRs, AGENTS.md, the docs app), or drop the trailers. Whichever it is, doing it in one sweep is cheaper than the recurring review noise, and it should land as its own change rather than riding along on an unrelated capability PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions