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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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