forgedock 1.1.1 → 1.1.2

package/examples/forgedock-demo/README.md

@@ -1,6 +1,6 @@
 # ForgeDock Demo — A Risk-Free First Pipeline Run
 
-A tiny **Notes API** (~300 lines, zero dependencies) with five pre-written
+A tiny **Notes API** (~400 lines, zero dependencies) with twenty pre-written
 issues. It exists so you can watch ForgeDock investigate, build, review, and
 merge a change **without touching your real codebase**.
 
@@ -14,9 +14,10 @@ Trying ForgeDock on your own project means trusting an AI pipeline with real
 code on your very first run. This demo removes that risk: it's a self-contained
 sandbox where every issue is small, fast, and safe to break.
 
-The API has a couple of **intentional, clearly-labelled flaws** (a missing auth
-check, an unsafe query path) so that ForgeDock's `/review-pr` agents have real
-findings to surface — that's the part that makes the review feel impressive.
+The API has a handful of **intentional, clearly-labelled flaws** (a missing auth
+check, two injection-vulnerable query paths, a mass-assignment gap) so that
+ForgeDock's `/review-pr` agents have real findings to surface — that's the part
+that makes the review feel impressive.
 
 ---
 
@@ -27,11 +28,11 @@ forgedock-demo/
 ├── src/
 │   ├── server.js        # built-in http server + router (no Express)
 │   ├── router.js        # (added by Issue #3)
-│   ├── routes/notes.js  # CRUD handlers — has the intentional flaws
-│   ├── db.js            # in-memory store
+│   ├── routes/notes.js  # CRUD + count/tags/patch handlers — has intentional flaws
+│   ├── db.js            # in-memory store with tags, createdAt, archived fields
 │   └── auth.js          # bearer-token check
 ├── scripts/smoke.js     # dependency-free smoke test (npm run smoke)
-├── issues/              # the 5 pre-written issue specs
+├── issues/              # 20 graded issue specs
 ├── forge.yaml           # minimal working ForgeDock config
 ├── labels.json          # workflow + priority labels
 └── bootstrap.sh         # one command to stand up the live repo
@@ -52,20 +53,37 @@ npm run smoke               # runs the smoke test
 
 ---
 
-## The five demo issues
-
-Each issue targets a different pipeline strength and is scoped to finish fast.
-
-| # | Type | Title | What it shows |
-|---|------|-------|---------------|
-| 1 | Bug / security | DELETE is missing an auth check | Simplest fix — fastest run |
-| 2 | Feature / security | Safe filtering for `GET /notes` | Investigation + architecture |
-| 3 | Refactor | Extract the router module | "No behavior change" review |
-| 4 | Performance | O(1) `findById` | Investigation phase tracing the hot path |
-| 5 | Docs | Add an API reference | Pipeline handles non-code work |
+## The twenty demo issues
+
+Each issue targets a different pipeline strength and difficulty tier.
+Issues 1–5 are the original quick-start set; issues 6–20 expand the corpus
+for statistically meaningful one-shot benchmark runs.
+
+| # | Difficulty | Type | Title |
+|---|-----------|------|-------|
+| 1 | Easy | Bug / security | DELETE is missing an auth check |
+| 2 | Medium | Feature / security | Safe filtering for `GET /notes` |
+| 3 | Easy | Refactor | Extract the router module |
+| 4 | Medium | Performance | O(1) `findById` |
+| 5 | Easy | Docs | Add an API reference |
+| 6 | Medium | Bug | POST stores malformed tags without validation |
+| 7 | Medium | Bug | Negative `?offset=` returns wrong notes instead of 400 |
+| 8 | Hard | Bug / security | PATCH allows mass-assignment of owner and secret |
+| 9 | Hard | Bug / security | GET /notes/count is vulnerable to expression injection |
+| 10 | Easy | Feature | Add `?sort=` parameter to GET /notes |
+| 11 | Medium | Feature | Allow PATCH to update tags |
+| 12 | Hard | Feature | POST /notes/bulk for all-or-nothing batch creation |
+| 13 | Hard | Feature | Archive/soft-delete with `?archived=` list filter |
+| 14 | Easy | Refactor | Extract title validation into validate.js |
+| 15 | Medium | Refactor | Centralize auth enforcement with a protected route flag |
+| 16 | Hard | Refactor | Extract generic store machinery into store.js |
+| 17 | Easy | Performance | Replace O(n²) tag de-dup in listTags with a Set |
+| 18 | Medium | Performance | Remove unnecessary O(n²) sort before pagination slice |
+| 19 | Easy | Docs | Complete API reference covering all endpoints |
+| 20 | Easy | Docs | Document the intentional-flaw and graded-issue convention |
 
 Full specs live in [`issues/`](./issues). When you run `bootstrap.sh`, these
-become real GitHub issues #1–#5 in your demo repo, in this order.
+become real GitHub issues #1–#20 in your demo repo, in this order.
 
 ---
 
@@ -87,7 +105,7 @@ credentials is creating the actual repo. One command does it:
 2. Push this codebase to `main`.
 3. Create the workflow + priority labels (via `npx forgedock labels setup`,
    falling back to `labels.json`).
-4. File the five issues from [`issues/`](./issues).
+4. File all twenty issues from [`issues/`](./issues).
 
 Then:
 
@@ -106,8 +124,9 @@ gate, open a PR, review it, and merge — all on a repo you can safely throw awa
 
 ## After your first run
 
-Try `/work-on 2` through `/work-on 5` to see the other pipeline phases, or run
-`/orchestrate` to let ForgeDock work several issues in parallel.
+Try `/work-on 2` through `/work-on 20` to see the full range of pipeline phases
+and issue types, or run `/orchestrate` to let ForgeDock work several issues in
+parallel.
 
 When you're comfortable, point ForgeDock at your real project — you've already
 seen exactly what it does.

package/examples/forgedock-demo/issues/06-bug-tags-type-validation.md

@@ -0,0 +1,43 @@
+---
+title: "fix(notes): POST /notes stores malformed tags without validation"
+labels: ["bug", "priority:P2"]
+difficulty: "medium"
+---
+
+## Problem
+
+`POST /notes` accepts a `tags` field from the request body but stores it without
+checking that it is an array. When a caller passes `"tags": 42` (or any non-array
+value), the malformed value is saved to the in-memory store. A subsequent
+`GET /notes?tag=work` then throws an uncaught `TypeError: n.tags.includes is not
+a function` from the tag-filter in `listNotes()`, returning a 500 response for
+all future tag-filtered requests — until the server is restarted.
+
+## Steps to Reproduce
+
+```bash
+# 1. Create a note with malformed tags
+curl -s -X POST http://localhost:3000/notes \
+  -H "Authorization: Bearer demo-token" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"bad","tags":99}' | jq .
+
+# 2. Any tag-filtered list now 500s
+curl -s "http://localhost:3000/notes?tag=work" | jq .
+# => {"error":"n.tags.includes is not a function"}
+```
+
+## Affected Files
+
+1. `src/routes/notes.js` — `createNote()` must validate that `tags`, when
+   supplied, is an array. Return 400 if it is not.
+
+## Acceptance Criteria
+
+- [ ] `POST /notes` with `"tags": 42` returns `400 Bad Request`.
+- [ ] `POST /notes` with `"tags": ["work"]` still succeeds (201).
+- [ ] `GET /notes?tag=work` works correctly after a valid note with tags is created.
+- [ ] `npm run smoke` still passes.
+
+> This issue exercises the **validation gap** pattern — the pipeline should
+> add a type check at the write boundary so the read path stays safe.

package/examples/forgedock-demo/issues/07-bug-negative-offset-pagination.md

@@ -0,0 +1,42 @@
+---
+title: "fix(notes): negative ?offset= returns wrong notes instead of 400"
+labels: ["bug", "priority:P2"]
+difficulty: "medium"
+---
+
+## Problem
+
+`GET /notes?offset=-1` silently applies JavaScript's negative-index slice
+semantics (`Array.prototype.slice(-1)` returns the last element) instead of
+returning a client error. A caller expecting an empty or 400 response receives
+the final note in the list, which is confusing and incorrect.
+
+## Steps to Reproduce
+
+```bash
+# List all notes first
+curl -s http://localhost:3000/notes | jq '.notes | length'
+# => 3
+
+# Negative offset returns the last note — unexpected
+curl -s "http://localhost:3000/notes?offset=-1" | jq '.notes'
+# => [{...note 3...}]
+
+# Expected: 400 Bad Request or normalized to 0
+```
+
+## Affected Files
+
+1. `src/routes/notes.js` — `listNotes()` must clamp `offset` to a non-negative
+   integer (reject with 400, or normalize to 0) before passing it to
+   `Array.prototype.slice`.
+
+## Acceptance Criteria
+
+- [ ] `GET /notes?offset=-1` returns `400 Bad Request` with a clear error message.
+- [ ] `GET /notes?offset=0` still returns all notes.
+- [ ] `GET /notes?offset=1&limit=2` returns notes starting from index 1.
+- [ ] `npm run smoke` still passes.
+
+> This issue demonstrates that **numeric input validation** is a separate concern
+> from type validation — the value is a number but falls outside the accepted range.

package/examples/forgedock-demo/issues/08-bug-patch-mass-assignment.md

@@ -0,0 +1,49 @@
+---
+title: "fix(notes): PATCH /notes/:id allows mass-assignment of owner and secret"
+labels: ["bug", "security", "priority:P1"]
+difficulty: "hard"
+---
+
+## Problem
+
+`PATCH /notes/:id` lets any authenticated caller overwrite the `owner` and
+`secret` fields alongside `title` and `body`. This is a mass-assignment
+vulnerability: a caller can flip `"secret": true` notes to `false`, making them
+visible in unauthenticated `GET /notes` responses, or reassign `owner` to
+impersonate another user.
+
+Unlike issue #1 (which has no auth check at all), this endpoint does require a
+token — the flaw is that it accepts a too-wide field set.
+
+## Steps to Reproduce
+
+```bash
+# Flip a secret note to non-secret without knowing its content
+curl -s -X PATCH http://localhost:3000/notes/2 \
+  -H "Authorization: Bearer demo-token" \
+  -H "Content-Type: application/json" \
+  -d '{"secret":false}' | jq .
+# => note is now visible to unauthenticated callers
+
+# Confirm it is now publicly listed
+curl -s http://localhost:3000/notes | jq '[.notes[] | select(.id==2)]'
+# => [{...secret note now visible...}]
+```
+
+## Affected Files
+
+1. `src/routes/notes.js` — `updateNote()` must restrict the allowed fields to
+   `title` and `body` only. Attempts to set `owner` or `secret` should return
+   `400 Bad Request` with a message listing the disallowed fields.
+
+## Acceptance Criteria
+
+- [ ] `PATCH /notes/:id` with `{"secret": false}` returns `400 Bad Request`.
+- [ ] `PATCH /notes/:id` with `{"owner": "hacker"}` returns `400 Bad Request`.
+- [ ] `PATCH /notes/:id` with `{"title": "new"}` still succeeds and updates the title.
+- [ ] `PATCH /notes/:id` with both `{"title": "new", "secret": false}` returns `400`.
+- [ ] `npm run smoke` still passes.
+
+> This issue covers the **mass-assignment / over-permissive write** pattern — a
+> common class of security bugs where an update endpoint accepts more fields than
+> it should.

package/examples/forgedock-demo/issues/09-bug-count-injection.md

@@ -0,0 +1,47 @@
+---
+title: "fix(notes): GET /notes/count is vulnerable to expression injection"
+labels: ["bug", "security", "priority:P1"]
+difficulty: "hard"
+---
+
+## Problem
+
+`GET /notes/count` builds its `db.query()` where-clause by concatenating the raw
+`?owner=` query parameter into a string: `'owner === "' + owner + '"'`. This is
+the same injection class as the `?where=` flaw in issue #2, but in a new
+endpoint that issue #2's fix does not cover.
+
+A caller can inject arbitrary JavaScript: `?owner=" || true; //` would evaluate
+to `owner === "" || true; //` — matching every note and leaking the real count
+regardless of owner.
+
+## Steps to Reproduce
+
+```bash
+# Normal count
+curl -s "http://localhost:3000/notes/count?owner=alice" | jq .
+# => {"count":2}
+
+# Injection — count all notes regardless of owner
+curl -s 'http://localhost:3000/notes/count?owner=" || true; //' | jq .
+# => {"count":3}  (all notes leaked)
+```
+
+## Affected Files
+
+1. `src/routes/notes.js` — `countNotes()` must not build a `db.query()` clause
+   via string concatenation. Replace the `db.query()` call with a direct
+   `db.all().filter()` using strict equality checks on typed values.
+
+## Acceptance Criteria
+
+- [ ] `GET /notes/count?owner=alice` returns `{"count": 2}`.
+- [ ] `GET /notes/count?owner=" || true; //` returns `{"count": 0}` (no match,
+  not a leak).
+- [ ] `GET /notes/count?secret=true` returns the correct count of secret notes.
+- [ ] `GET /notes/count` (no filters) returns the total note count.
+- [ ] `npm run smoke` still passes.
+
+> This issue reinforces the pattern from issue #2 — injection through dynamic
+> `db.query()` clause building — but in a different endpoint, demonstrating that
+> fixing the first occurrence doesn't automatically close the class.

package/examples/forgedock-demo/issues/10-feature-sort-param.md

@@ -0,0 +1,39 @@
+---
+title: "feat(notes): add ?sort= parameter to GET /notes"
+labels: ["feature", "priority:P3"]
+difficulty: "easy"
+---
+
+## Problem
+
+`GET /notes` always returns notes in insertion order. There is no way for a
+caller to request notes sorted by `title` or `createdAt` without fetching all
+notes and sorting client-side.
+
+## Proposed Solution
+
+Add a `?sort=` query parameter to `GET /notes` that accepts:
+
+- `sort=id` — sort by numeric id ascending (current default behavior)
+- `sort=title` — sort alphabetically by `title`
+- `sort=createdAt` — sort by `createdAt` string (ISO 8601, lexicographic sort
+  is equivalent to chronological for the demo's fixed-format timestamps)
+
+An unknown `sort` value should return `400 Bad Request`.
+
+## Affected Files
+
+1. `src/routes/notes.js` — extend `listNotes()` to read a `sort` query param
+   and apply the appropriate comparison before returning the results array.
+
+## Acceptance Criteria
+
+- [ ] `GET /notes?sort=title` returns notes sorted alphabetically by title.
+- [ ] `GET /notes?sort=createdAt` returns notes sorted oldest-first.
+- [ ] `GET /notes?sort=id` returns notes in id order (same as current default).
+- [ ] `GET /notes?sort=unknown` returns `400 Bad Request`.
+- [ ] `GET /notes` (no sort param) still returns notes in insertion order.
+- [ ] `npm run smoke` still passes.
+
+> A focused, additive feature — the pipeline should confirm no existing
+> behavior changes and that the 400 guard is present.

package/examples/forgedock-demo/issues/11-feature-patch-tags.md

@@ -0,0 +1,37 @@
+---
+title: "feat(notes): allow PATCH /notes/:id to update tags"
+labels: ["feature", "priority:P3"]
+difficulty: "medium"
+---
+
+## Problem
+
+`PATCH /notes/:id` currently only updates `title` and `body` (after the fix from
+issue #8). There is no way to add or replace tags on an existing note without
+deleting and recreating it.
+
+## Proposed Solution
+
+Extend `PATCH /notes/:id` to accept an optional `tags` field. The value must be
+an array of strings (validate at write time, same fix pattern as issue #6).
+When supplied, it replaces the note's existing `tags` array entirely — a full
+replacement (not a merge/append), keeping the semantics simple.
+
+## Affected Files
+
+1. `src/routes/notes.js` — `updateNote()` should accept `tags` in addition to
+   `title` and `body`. Validate that `tags` is an array when present; return
+   `400` if it is not.
+
+## Acceptance Criteria
+
+- [ ] `PATCH /notes/:id` with `{"tags": ["work", "urgent"]}` replaces the note's
+  tags and returns the updated note.
+- [ ] `PATCH /notes/:id` with `{"tags": 99}` returns `400 Bad Request`.
+- [ ] Omitting `tags` from the patch body leaves existing tags unchanged.
+- [ ] `GET /notes?tag=urgent` returns the patched note after its tags are updated.
+- [ ] `npm run smoke` still passes.
+
+> This feature has a deliberate dependency on issue #8 being fixed first — tags
+> must not be writable via mass-assignment before they are intentionally writable
+> via a validated field. Run issue #8 before this one.

package/examples/forgedock-demo/issues/12-feature-bulk-create.md

@@ -0,0 +1,42 @@
+---
+title: "feat(notes): add POST /notes/bulk for all-or-nothing batch creation"
+labels: ["feature", "priority:P3"]
+difficulty: "hard"
+---
+
+## Problem
+
+Creating multiple notes requires a separate `POST /notes` call per note.
+For loading test fixtures or seeding data, callers want to create several notes
+in one request, with the guarantee that either all are created or none are
+(all-or-nothing semantics).
+
+## Proposed Solution
+
+Add `POST /notes/bulk` (protected) that accepts `{ "notes": [...] }` where each
+item has the same shape as the single-note `POST /notes` body. The endpoint
+must:
+
+1. Validate that the top-level `notes` field is a non-empty array.
+2. Validate that every item has a non-empty `title`.
+3. Only insert any notes if all items are valid (all-or-nothing).
+4. Return `{ "notes": [...created notes] }` with status 201 on success.
+
+## Affected Files
+
+1. `src/routes/notes.js` — add a new `bulkCreateNotes()` handler.
+2. `src/server.js` — register `POST /notes/bulk` in the route table **before**
+   the existing `POST /notes` entry so the literal path match takes priority.
+
+## Acceptance Criteria
+
+- [ ] `POST /notes/bulk` with a valid array creates all notes and returns 201.
+- [ ] If any note is missing `title`, returns `400` and no notes are created.
+- [ ] `POST /notes/bulk` without a token returns `401`.
+- [ ] `POST /notes/bulk` with `{"notes": []}` returns `400`.
+- [ ] `GET /notes` after a successful bulk create shows the new notes.
+- [ ] `npm run smoke` still passes.
+
+> This feature requires careful thought about route ordering (the `/bulk`
+> literal path must not be shadowed by `POST /notes$`) and about transaction
+> semantics in the in-memory store.

package/examples/forgedock-demo/issues/13-feature-archive-notes.md

@@ -0,0 +1,46 @@
+---
+title: "feat(notes): implement archive/soft-delete with ?archived= list filter"
+labels: ["feature", "priority:P3"]
+difficulty: "hard"
+---
+
+## Problem
+
+`DELETE /notes/:id` permanently removes a note. There is no way to soft-delete
+(archive) a note and later restore it or filter archived notes out of the default
+listing. The `archived` field already exists in the data model but is not
+writable or filterable.
+
+## Proposed Solution
+
+1. Add `POST /notes/:id/archive` (protected) — sets `archived: true` on the
+   note. Returns the updated note.
+2. Add `POST /notes/:id/restore` (protected) — sets `archived: false`.
+3. Extend `GET /notes` to support `?archived=true` (list only archived notes),
+   `?archived=false` (list only non-archived notes — new default behavior), and
+   no `archived` param (list all, preserving today's behavior).
+
+By default (no `?archived=` param) `GET /notes` should still return all notes,
+including archived ones, to avoid a breaking change for the existing smoke test.
+
+## Affected Files
+
+1. `src/routes/notes.js` — add `archiveNote()` and `restoreNote()` handlers;
+   extend `listNotes()` to apply an `archived` filter when the param is present.
+2. `src/server.js` — register the two new routes:
+   - `POST /notes/:id/archive`
+   - `POST /notes/:id/restore`
+
+## Acceptance Criteria
+
+- [ ] `POST /notes/1/archive` (with token) returns `{"note": {..., "archived": true}}`.
+- [ ] `POST /notes/1/restore` (with token) returns `{"note": {..., "archived": false}}`.
+- [ ] `GET /notes?archived=false` omits archived notes.
+- [ ] `GET /notes?archived=true` returns only archived notes.
+- [ ] `GET /notes` (no param) returns all notes regardless of archived status.
+- [ ] Both new routes return `401` without a token and `404` for unknown ids.
+- [ ] `npm run smoke` still passes.
+
+> A multi-route feature that touches both handler and server wiring. Good for
+> testing whether the pipeline correctly sequences route registration and
+> confirms no regression on the existing list/create/delete flows.

package/examples/forgedock-demo/issues/14-refactor-extract-title-validation.md

@@ -0,0 +1,41 @@
+---
+title: "refactor(notes): extract title validation into a shared validate.js module"
+labels: ["refactor", "priority:P3"]
+difficulty: "easy"
+---
+
+## Problem
+
+`createNote()` in `src/routes/notes.js` has an inline `if (!title)` guard. When
+the bulk-create endpoint (issue #12) is added, the same check will need to be
+duplicated. Any future handler that creates or modifies a note title will face
+the same duplication.
+
+This is a pure refactor — no behavior change, no new validation rules.
+
+## Proposed Solution
+
+Extract the title-presence check into a new `src/validate.js` module that
+exports a single function: `validateNote({ title })`. The function throws a
+`400`-status error if `title` is falsy, identical to the current inline guard.
+`createNote()` (and, if issue #12 is already merged, `bulkCreateNotes()`) should
+call `validateNote()` instead of the inline check.
+
+## Affected Files
+
+1. `src/validate.js` (NEW) — exports `validateNote({ title })`.
+2. `src/routes/notes.js` — replace the inline `if (!title)` block with
+   `validateNote({ title })` imported from `../validate`.
+
+## Acceptance Criteria
+
+- [ ] `POST /notes` without a `title` still returns `400` with the same error
+  message as before.
+- [ ] `src/routes/notes.js` no longer contains a bare `if (!title)` guard —
+  that logic lives only in `src/validate.js`.
+- [ ] `npm run smoke` still passes.
+- [ ] No behavior change in any endpoint.
+
+> A zero-behavior-change refactor. The review agents should confirm that the
+> 400 path, the error message, and all other responses are byte-for-byte
+> identical to the pre-refactor baseline.

package/examples/forgedock-demo/issues/15-refactor-protected-route-flag.md

@@ -0,0 +1,43 @@
+---
+title: "refactor(server): centralize auth enforcement with a protected flag in the route table"
+labels: ["refactor", "priority:P3"]
+difficulty: "medium"
+---
+
+## Problem
+
+Authorization (`requireToken`) is enforced by each route handler individually.
+As routes grow, there is no single place to see which routes are protected — a
+reviewer must read every handler. Missing a `requireToken` call in a new handler
+is exactly how issue #1's bug was introduced.
+
+## Proposed Solution
+
+Add a boolean `protected` flag as the fourth element of each route-table entry
+in `src/server.js`. The server's request dispatch loop should call
+`requireToken(req)` centrally, before the handler is invoked, whenever the flag
+is `true`. Handlers that currently call `requireToken()` themselves should have
+that call removed (it is now redundant).
+
+This is a pure refactor — every endpoint's authorization behavior must remain
+identical.
+
+## Affected Files
+
+1. `src/server.js` — add `protected: true/false` to each TABLE entry; call
+   `requireToken(req)` in the dispatch loop when the flag is set.
+2. `src/routes/notes.js` — remove all `requireToken(req)` calls from handlers
+   that will be protected by the table flag instead.
+
+## Acceptance Criteria
+
+- [ ] `POST /notes` without a token still returns `401`.
+- [ ] `PATCH /notes/:id` without a token still returns `401`.
+- [ ] `DELETE /notes/:id` still returns its current response (intentionally
+  unprotected in the baseline — issue #1 is not yet fixed).
+- [ ] No `requireToken(req)` call remains inside any route handler.
+- [ ] `npm run smoke` still passes.
+- [ ] No behavior change in any endpoint.
+
+> This refactor makes the authorization surface visible at a glance —
+> a pattern that directly prevents the class of bug introduced in issue #1.

package/examples/forgedock-demo/issues/16-refactor-extract-store.md

@@ -0,0 +1,45 @@
+---
+title: "refactor(db): extract the generic array-store machinery into store.js"
+labels: ["refactor", "priority:P3"]
+difficulty: "hard"
+---
+
+## Problem
+
+`src/db.js` conflates two things: the generic in-memory array/index operations
+(`all`, `findById`, `insert`, `remove`, `reset`) and the Notes-specific seed
+data and field defaults. If a second resource (e.g. users) were added, all of
+that generic machinery would need to be duplicated.
+
+This is a pure refactor — no behavior change, no new features.
+
+## Proposed Solution
+
+Extract the generic store machinery into `src/store.js`, exporting a factory
+function `createStore(seed, defaults)`. The returned object exposes:
+`all`, `findById`, `insert`, `remove`, `reset`.
+
+`src/db.js` becomes a thin wrapper: it calls `createStore(SEED, { secret:
+false, tags: [], archived: false })` and re-exports the resulting methods plus
+`query` and `bubbleSortById` (which remain in `db.js` as Notes-specific logic).
+
+The public API visible to `routes/notes.js` must be byte-for-byte compatible.
+
+## Affected Files
+
+1. `src/store.js` (NEW) — generic `createStore(seed, defaults)` factory.
+2. `src/db.js` — delegates `all`/`findById`/`insert`/`remove`/`reset` to the
+   store instance; keeps `query`/`bubbleSortById`.
+
+## Acceptance Criteria
+
+- [ ] `db.all()`, `db.findById()`, `db.insert()`, `db.remove()`, `db.reset()`
+  all behave identically to today.
+- [ ] `db.query()` and `db.bubbleSortById()` are unchanged.
+- [ ] No code in `src/routes/notes.js` or `src/server.js` changes.
+- [ ] `npm run smoke` still passes.
+- [ ] No behavior change in any endpoint.
+
+> A structural refactor that introduces an abstraction boundary — the review
+> agents should verify that the public interface is preserved exactly and that
+> no observable behavior changes.

package/examples/forgedock-demo/issues/17-perf-tags-dedup-set.md

@@ -0,0 +1,35 @@
+---
+title: "perf(notes): replace O(n²) tag de-duplication in listTags with a Set"
+labels: ["performance", "priority:P3"]
+difficulty: "easy"
+---
+
+## Problem
+
+`GET /notes/tags` de-duplicates tags using a nested loop: for every tag in every
+note it scans the entire `unique` array to check for a duplicate. This is O(n²)
+on the total tag count. With a large corpus of notes and many tags, this becomes
+slow.
+
+The fix is a one-line change to use a `Set` for deduplication instead.
+
+## Investigation Hint
+
+Before optimizing, confirm where the nested loop is and calculate the actual
+time complexity. Verify that the `Set`-based replacement produces the same
+output (same tags, same order — first-seen wins, matching the current
+behavior).
+
+## Affected Files
+
+1. `src/routes/notes.js` — `listTags()`: replace the nested-loop uniqueness
+   check with a `Set`.
+
+## Acceptance Criteria
+
+- [ ] `GET /notes/tags` returns the same tags in first-seen order as before.
+- [ ] The nested loop in `listTags()` is removed.
+- [ ] `npm run smoke` still passes.
+
+> A focused, single-function perf fix. The pipeline should confirm output
+> equivalence before and after the change, not just that the test passes.

package/examples/forgedock-demo/issues/18-perf-remove-redundant-sort.md

@@ -0,0 +1,37 @@
+---
+title: "perf(notes): remove unnecessary O(n²) sort before pagination slice"
+labels: ["performance", "priority:P3"]
+difficulty: "medium"
+---
+
+## Problem
+
+`GET /notes?limit=...&offset=...` runs `db.bubbleSortById(results)` before
+slicing — an O(n²) bubble sort — even though `results` is already in id order
+(the in-memory store is maintained in insertion order and ids are
+monotonically increasing). The sort is both redundant and slow.
+
+## Investigation Hint
+
+Trace the insertion order invariant through `db.insert()` and `db.reset()` to
+confirm that `notes` is always in id-ascending order. Then verify that
+`db.bubbleSortById` does not change the element order for already-sorted input
+(it should not — confirm this, don't assume it). Once confirmed, the sort call
+is safe to remove.
+
+## Affected Files
+
+1. `src/routes/notes.js` — `listNotes()`: remove the `db.bubbleSortById(results)`
+   call in the pagination branch. Slice `results` directly.
+
+## Acceptance Criteria
+
+- [ ] `GET /notes?limit=2` returns the same two notes as before (first two by
+  id).
+- [ ] `GET /notes?offset=1&limit=1` returns the same note as before.
+- [ ] The `db.bubbleSortById` call is no longer present in `listNotes()`.
+- [ ] `npm run smoke` still passes.
+
+> This issue showcases the **investigation phase confirming an invariant** —
+> the pipeline must verify the insertion-order guarantee before removing the
+> sort, rather than blindly deleting it.