flowchart TB
  ask["'Add rate limiting
to the API'"]:::in --> agent["Coding agent"]:::model
  agent --> diff["A plausible diff
clean, confident, fast"]:::warn
  diff --> a["Fixed window,
not sliding"]:::bad
  diff --> b["Reset header
in milliseconds"]:::bad
  diff --> c["Edited a test
to stay green"]:::bad
  a --> rev["Human review"]:::rev
  b --> rev
  c --> rev
  rev --> boom["The only gate
is your attention"]:::boom
  classDef in fill:#DCEBFE,stroke:#0D1B33,color:#0D1B33;
  classDef model fill:#EEE6FF,stroke:#0D1B33,color:#0D1B33;
  classDef warn fill:#FEF3C7,stroke:#0D1B33,color:#0D1B33;
  classDef bad fill:#FEE4E2,stroke:#0D1B33,color:#0D1B33;
  classDef rev fill:#fff,stroke:#0D1B33,color:#0D1B33;
  classDef boom fill:#0D1B33,stroke:#0D1B33,color:#fff;
          

flowchart TB
  init["specify init
.specify/ + agent commands"]:::setup
  init --> con["/speckit.constitution
constitution.md · 5 principles, v1.0.0"]:::once
  con --> spec["/speckit.specify
spec.md · 17 FRs, 8 success criteria"]:::gen
  spec --> clar["/speckit.clarify
optional: interviews you on the gaps"]:::opt
  clar --> plan["/speckit.plan
plan.md, research.md, data-model.md, contracts/"]:::gen
  plan --> tasks["/speckit.tasks
tasks.md · 35 ordered tasks"]:::gen
  tasks --> impl["/speckit.implement
writes the code"]:::gen
  impl --> out["8 documents and a diff.
Every document a thing
the agent was asked to follow"]:::warn
  classDef setup fill:#DCEBFE,stroke:#0D1B33,color:#0D1B33;
  classDef once fill:#D1FAE5,stroke:#0D1B33,color:#0D1B33;
  classDef gen fill:#EEE6FF,stroke:#0D1B33,color:#0D1B33;
  classDef opt fill:#fff,stroke:#0D1B33,color:#0D1B33,stroke-dasharray:5 4;
  classDef warn fill:#FEF3C7,stroke:#0D1B33,color:#0D1B33;
          

specs/002-rate-limit/
├── spec.md          17 FRs · 8 success criteria · 5 stories
├── plan.md          constitution check · the delta table
├── research.md      6 decisions, each with the alternative
│                    it rejected and the reason
├── data-model.md    the interface, before any code exists
├── quickstart.md    how to exercise it once it exists
├── contracts/
│   └── rate-limit.md    the HTTP surface, header by header
├── checklists/
│   └── review.md        what a human confirms after the gate
└── tasks.md         35 tasks, and 19 of them come back
                     marked [FENCED]  ← hold that thought

// specs/002-rate-limit/data-model.md · the contract

export interface RateLimitDecision {
  allowed:    boolean  // false means refuse with 429
  limit:      number
  remaining:  number   // FR-011 · pinned at 0, never negative
  resetAt:    number   // epoch MILLISECONDS in here
  retryAfter: number   // FR-007 · whole seconds, floored at 1
}

export interface RateLimiter {
  check(key: string, now: number): RateLimitDecision
  size(now: number): number   // FR-015 · memory made assertable
}

export function createRateLimiter(o: RateLimiterOptions): RateLimiter

// FR-016  Both methods take `now`. Neither reads a clock.
// FR-017  A string key, not a request. The limiter has never
//         heard of a header, a path, or HTTP.

spec.md
FR-005  At 59999 ms after a caller's tenth request, that
        caller MUST still be refused. At 60001 ms, exactly
        one further request MUST be allowed, and no more.
                          ↓
spec.md · User Story 2, scenario 3
US2-3   Given the situation above, When a further request
        arrives immediately after that one, Then it is
        refused, because only one slot freed.
                          ↓
research.md
R3      a hit counts while  now - hitTime < 60000
                          ↓
tasks.md
T011    [FENCED] Exactly one request allowed at
        t + 60001, and the next one refused. Asserting
        the second call is refused is what
        distinguishes a sliding window from a bucket.
                          ↓
tests/api.test.ts    ← a maintainer writes this one

// tests/api.test.ts · written by hand, from T010–T014

const app = createApp({
  limiter: createRateLimiter({ limit: 10, windowMs: 60_000 }),
})
const hit = (now: number) =>
  app({ method: 'GET', path: '/items', headers: {},
       ip: '10.0.0.1', now })

it('frees exactly one slot as the oldest hit ages out', () => {
  for (let i = 0; i < 10; i++) expect(hit(0).status).toBe(200)

  // 1ms early: still blocked
  expect(hit(59_999).status).toBe(429)
  // 1ms late: exactly one slot has freed…
  expect(hit(60_001).status).toBe(200)
  // …and only one. A bucket would allow nine more here.
  expect(hit(60_001).status).toBe(429)
})

// No sleep, no timers, no network. `now` is an argument,
// so the whole window is exercised by passing numbers. SC-008

plan.md · Constitution Check
  [x] I.   Node and TypeScript
  [x] II.  Pure core, one impure edge
  [x] III. Behaviour-first testing
  [x] IV.  Fail loud
  [ ] V.   The agent fence  — Does not pass.
                            See Complexity Tracking.

plan.md · Complexity Tracking
  "Splitting the tests into a new file was rejected
   as routing around the fence rather than
   reporting it."

tasks.md · the header, before task one
  "[FENCED]: touches tests/api.test.ts, denied
   repo-wide by constraints.md. Authored by a
   maintainer, not an agent."
                        19 of the 35 tasks carry it

flowchart TB
  agent["Coding agent
proposes a diff"]:::model --> gate{"npm run gate
paths · types · tests"}:::gate
  gate -->|"any check red"| stop["Rejected
nothing merges"]:::bad
  gate -->|"all three green"| human["Human review
was the spec right?"]:::good
  human --> merge["Merge"]:::done
  stop -.->|"fix the cause,
never the gate"| agent
  classDef model fill:#EEE6FF,stroke:#0D1B33,color:#0D1B33;
  classDef gate fill:#FEF3C7,stroke:#0D1B33,color:#0D1B33;
  classDef bad fill:#FEE4E2,stroke:#0D1B33,color:#0D1B33;
  classDef good fill:#D1FAE5,stroke:#0D1B33,color:#0D1B33;
  classDef done fill:#0D1B33,stroke:#0D1B33,color:#fff;
          

/speckit.plan · /speckit.tasks · /speckit.implement
  35 tasks · 19 marked FENCED · 2 source files written

$ npm run gate

spec-driven gate

1. Allowed paths
        spec 002-rate-limit · 10 changed file(s) · base origin/main
  PASS  path guard  all 10 file(s) in bounds

2. Types
  PASS  typecheck

3. Tests
  ✓ tests/api.test.ts               (30 tests)
        11 regression, untouched · 19 acceptance, hand-written
  PASS  tests

summary
  PASS  path guard
  PASS  typecheck
  PASS  tests

GATE PASSED: the machine-checkable half is done.
Now the human half: the review checklist at the end of the spec.

// scripts/gate.mjs · the part that matters

const deny  = fencedList(read('constraints.md'), 'deny')
const spec  = activeSpec(changed)  // specs/<id>/ in the diff
const allow = fencedList(read(specFile), 'allow')

const denied  = changed.filter(f => matches(f, deny))
const outside = changed.filter(f =>
  !matches(f, deny) && !matches(f, allow))

if (denied.length || outside.length) {
  // out of bounds is not worth compiling
  fail('the diff went outside its allowed paths')
}

run('typecheck', 'npx', ['tsc', '--noEmit'])
run('tests',     'npx', ['vitest', 'run'])

// ↑ swap these two lines for pytest / go test / cargo test.
//   The path guard above is language-agnostic.

// activeSpec() reads specs/<id>/ out of the diff and
// refuses one that touches two specs at once. So a
// spec-kit spec.md works the moment you add an `allow`.

specs/002-rate-limit/checklists/review.md

## The boundary
[ ] A hit made at t still counts at t + 59999 and
    does not count at t + 60000. Both sides
    asserted, not just one
[ ] Nowhere in src/rate-limit.ts is there a window
    start, a bucket, or a modulo

## Units
[ ] resetAt inside the limiter is milliseconds, and
    the conversion to seconds happens exactly once

## The question the gate cannot ask
[ ] Is ten requests per sixty seconds actually the
    right limit for this service, or is it the
    number that appeared in the prompt?