forgedock 1.0.22 → 1.1.2

package/docs/superpowers/specs/2026-07-04-provenance-trail-design.md

@@ -0,0 +1,189 @@
+# Signed, Replayable Provenance Trail — Design Spec
+
+**Date:** 2026-07-04
+**Status:** Design — ready to build
+**Tracking:** #1318 (provenance layer), epic #1320 (five foundations of autonomy)
+**Depends on:** #1256 (durable engine run-log — replayability requires a committed step log)
+**Scope:** Integrity guarantee + replayability layer on top of the existing FORGE annotation protocol (#1291–1294). Every autonomous PR carries a signed attestation linking decisions → verification evidence → alternatives rejected.
+
+---
+
+## 1. Motivation
+
+For an organization to allow autonomous merges to production, every change needs a complete, verifiable record of *why it was made, what was verified, and what alternatives were considered and rejected* — reproducibly.
+
+Today provenance is scattered `FORGE:*` comments with no integrity guarantee:
+
+| Gap | Current state | Problem |
+|-----|--------------|---------|
+| Integrity | Comments are plain Markdown, mutable | Any party can edit or delete them after the fact |
+| Completeness | Each annotation covers one phase | No single artifact links decision → evidence → alternatives |
+| Replayability | State is prose — humans can read it but tools cannot deterministically replay it | Resume re-parses prose heuristically |
+| Attestation | No signed artifact exists | Human reviewers have no cryptographic basis to trust "the agent said it was safe" |
+
+**Trust, not capability, is the blocker to auto-merge.** This spec adds integrity + replayability + a signed attestation on top of the existing FORGE protocol, without replacing it.
+
+---
+
+## 2. Goals / Non-goals
+
+**Goals**
+- Each autonomous PR carries a `FORGE:PROVENANCE` attestation that links: investigation decision → build decisions → verification evidence → rejected alternatives.
+- A run is replayable from its provenance record + durable engine run-log (#1256).
+- The provenance record validates against the FORGE protocol conformance suite (#1291).
+- Integrity is achieved via a content hash over the structured annotation chain — no external PKI required for v1.
+
+**Non-goals**
+- Hardware-rooted signing (TPM, HSM) — out of scope for v1; the content hash gives tamper-evidence without it.
+- Retroactive provenance for runs completed before this spec ships.
+- Per-turn provenance (this spec is per-run / per-PR granularity, matching the durable engine's per-phase checkpoint).
+- Provenance for interactive `/work-on` runs (headless/orchestrated first, interactive later).
+
+---
+
+## 3. Locked Decisions
+
+1. **Attestation format: structured HTML comment (`FORGE:PROVENANCE`) on the PR.** Consistent with the existing annotation protocol. Readable by humans in the PR thread and queryable by the same text-contains filters used today.
+2. **Integrity mechanism: SHA-256 content hash over a canonical serialization of the annotation chain.** The hash is computed over the ordered sequence of `FORGE:*` annotation bodies (canonically serialized as JSON). Anyone with the run-log can recompute it.
+3. **Replayability: the durable engine run-log is the replay substrate.** The `FORGE:PROVENANCE` record carries a pointer to the run-log location (issue comment ID sequence). A conformant replayer reads those comments in order and reconstructs the pipeline state.
+4. **Chain of custody: each annotation carries a `seq` (sequence number) and `prev_hash` (hash of the prior annotation).** This forms a tamper-evident linked list. Adding, removing, or reordering annotations breaks the hash chain.
+5. **The attestation is written by the durable engine, not by individual phase agents.** Agents write their phase annotations as today; the engine writes the final `FORGE:PROVENANCE` after the merge gate passes.
+
+---
+
+## 4. Architecture
+
+### 4.1 Annotation Chain Extension
+
+Existing FORGE annotations gain two new fields (backward-compatible — consumers that do not understand them ignore them):
+
+```
+<!-- FORGE:INVESTIGATOR
+seq: 1
+prev_hash: "genesis"
+...existing fields...
+body_hash: "sha256:a1b2c3..."
+-->
+```
+
+| New field | Type | Description |
+|-----------|------|-------------|
+| `seq` | integer | Position in the annotation chain for this run (1-indexed) |
+| `prev_hash` | string | SHA-256 of the prior annotation's canonical body, or `"genesis"` for the first |
+| `body_hash` | string | SHA-256 of this annotation's canonical body (self-hash, written last) |
+
+**Canonical body**: the annotation content between the `<!-- FORGE:TAG` opening and the `-->` closing, with leading/trailing whitespace stripped and line endings normalized to `\n`, serialized as a UTF-8 JSON string.
+
+### 4.2 FORGE:PROVENANCE Annotation
+
+Written to the PR by the durable engine after the merge gate passes, before the merge commit:
+
+```html
+<!-- FORGE:PROVENANCE
+run_id: "run-abc123"
+issue: 1317
+pr: 1460
+pipeline_version: "1.0.21"
+agent_model: "claude-sonnet-4-6"
+
+chain:
+  - seq: 1  tag: INVESTIGATOR  comment_id: 2345678901  body_hash: "sha256:a1b2..."
+  - seq: 2  tag: ARCHITECT      comment_id: 2345678910  body_hash: "sha256:b2c3..."
+  - seq: 3  tag: BUILDER        comment_id: 2345678920  body_hash: "sha256:c3d4..."
+  - seq: 4  tag: REVIEWER       comment_id: 2345678930  body_hash: "sha256:d4e5..."
+  - seq: 5  tag: QUALITY_GATE   comment_id: 2345678940  body_hash: "sha256:e5f6..."
+  - seq: 6  tag: ECONOMICS      comment_id: 2345678950  body_hash: "sha256:f6a7..."
+
+chain_hash: "sha256:0123456789abcdef..."
+verification_passed: true
+alternatives_considered:
+  - "Inline fix without issue — rejected: no traceability"
+  - "Defer to manual review — rejected: low-risk score 0.82"
+merge_authorized_by: "economic-self-governance"
+timestamp: 2026-07-04T18:00:00Z
+forge_protocol_version: "1.0"
+-->
+<!-- FORGE:PROVENANCE:COMPLETE -->
+```
+
+**`chain_hash`**: SHA-256 of the concatenated `body_hash` values in `seq` order, joined with `\n`. Recomputable from the listed comment IDs alone.
+
+### 4.3 Replayability Contract
+
+A conformant replayer MUST be able to reconstruct the pipeline state for a given `run_id` by:
+
+1. Reading the `FORGE:PROVENANCE` annotation from the PR to get the `chain` (comment ID list).
+2. Fetching each comment in `seq` order from the GitHub API.
+3. Parsing each `FORGE:*` annotation body.
+4. Recomputing the `chain_hash` and asserting it matches the recorded value.
+5. Replaying the durable engine run-log (from `#1256`) for per-phase step details.
+
+Step 4 is the integrity check. A mismatch means the annotation chain was tampered with after the run.
+
+### 4.4 Conformance Suite Integration (#1291)
+
+The FORGE protocol conformance suite gains a new test category: **Provenance Conformance**.
+
+| Test | Pass condition |
+|------|---------------|
+| `P-01` | PR has exactly one `FORGE:PROVENANCE` annotation followed by `FORGE:PROVENANCE:COMPLETE` |
+| `P-02` | All `seq` values in the chain are contiguous starting from 1 |
+| `P-03` | Each `prev_hash` matches the `body_hash` of the prior annotation (or `"genesis"` for seq=1) |
+| `P-04` | `chain_hash` recomputes correctly from the listed `body_hash` values |
+| `P-05` | All annotations referenced in the chain are fetchable and parse as valid FORGE annotations |
+| `P-06` | `timestamp` is an ISO 8601 UTC datetime |
+| `P-07` | `forge_protocol_version` is present and a known value |
+
+### 4.5 Integration Points
+
+**Durable engine (`#1256`)**: After merge gate passes, the engine invokes `write_provenance()`:
+- Collects all annotation comment IDs from the run-log.
+- Fetches each annotation body and computes `body_hash` values.
+- Computes `chain_hash`.
+- Posts `FORGE:PROVENANCE` to the PR.
+
+**Quality gate (`/quality-gate`)**: Gains a new check: `PROVENANCE` — verifies `P-01` through `P-07`. Fails the gate if any check fails on an autonomous run. Human-initiated runs emit a warning (not a hard failure) if provenance is absent.
+
+**`/replay` command**: Uses the `chain` from `FORGE:PROVENANCE` as the replay index instead of scanning all comments for `FORGE:*` annotations. This is faster and guaranteed-ordered.
+
+---
+
+## 5. Implementation Plan
+
+### Increment 1: Chain fields on existing annotations (non-breaking)
+- Modify durable engine to write `seq`, `prev_hash`, and `body_hash` on each annotation it posts.
+- No consumer changes required — fields are additive.
+- Validate that existing annotations without these fields are still parseable.
+
+### Increment 2: FORGE:PROVENANCE annotation
+- Engine writes `FORGE:PROVENANCE` to the PR after merge gate passes.
+- Includes `chain`, `chain_hash`, `verification_passed`, `timestamp`.
+- `/replay` updated to use the chain index when present.
+
+### Increment 3: Conformance tests + quality gate check
+- Add `P-01` through `P-07` tests to the conformance suite (#1291).
+- Add `PROVENANCE` check to `/quality-gate` (warning on human runs, hard failure on autonomous runs).
+
+### Increment 4: Replayability validation
+- Add a `verify_provenance(run_id)` script to `scripts/`.
+- Script fetches the PR, reads `FORGE:PROVENANCE`, fetches all chained comments, recomputes `chain_hash`, and reports pass/fail.
+
+---
+
+## 6. Open Questions
+
+- **Comment mutability**: GitHub allows editing comments. The hash chain detects tampering but does not prevent it. For v2, consider posting annotations to an immutable artifact (e.g., a GitHub Release asset or a signed commit note) as an optional hardened mode.
+- **`body_hash` for legacy annotations**: If an annotation was written before this spec (no `body_hash` field), the chain is broken. Acceptable for v1: the `FORGE:PROVENANCE` chain only covers annotations written by the durable engine (which will be updated atomically). Legacy runs have no provenance claim.
+- **`alternatives_considered` source**: In v1 this is written by the engine based on the economics decision (#1317) and the quality-gate outcome. A richer alternatives record (e.g., architect alternatives from `FORGE:ARCHITECT`) can be pulled in a later increment.
+
+---
+
+## 7. References
+
+- #1318 — this issue
+- #1291–1294 — FORGE protocol conformance suite (seed schema)
+- #1256 — durable engine (run-log substrate; required for replayability)
+- #1315 — outcome-based acceptance gate (supplies "what was verified" evidence)
+- #1317 — economic self-governance (supplies `merge_authorized_by` and `alternatives_considered`)
+- #1320 — five foundations epic (provenance layer)
+- `docs/spec/forge-protocol-v1.md` — FORGE annotation protocol v1.0

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.