From d7f9708292ae261ad9c5acede15d5fb37173c87b Mon Sep 17 00:00:00 2001 From: Erik Hjelm Fjeldheim Date: Fri, 25 Sep 2026 12:35:34 -0600 Subject: [PATCH 1/8] docs: #4 workflow guide and AI decision log MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/WORKFLOW.md — branching, conventional commits, PR size and review expectations. Records the two corrections the group made to the process: implement each issue from its requirements rather than splitting the archived prototype, and drop the formal pre-coding plan comment in favour of clear issues plus PR descriptions that say what was done and tested. docs/AI-USAGE.md — rewritten as a decision log, one entry per PR: what we asked for, what we took, what we changed or rejected and why, and what the reviewer pushed back on. Opens with an honest account of the scaffold prototype and why it was closed unmerged, including the three bugs the smoke suite caught that the unit tests had missed. README.md — project intro, getting started, milestone table, and links to both documents. Co-Authored-By: opencode --- README.md | 55 +++++++++++++++++++++++++++++++ docs/AI-USAGE.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/WORKFLOW.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 222 insertions(+) create mode 100644 docs/AI-USAGE.md create mode 100644 docs/WORKFLOW.md diff --git a/README.md b/README.md index ddbfccc..22b7817 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,58 @@ Repository for team IT2810-H26-T19 in IT2810-H26. +**Crate** - a searchable catalog of albums. Search by word, filter and sort the +results, open an album for detail, and persist ratings, reviews and a personal +wantlist ("crate"). + +IT2810 (NTNU) Project 2. Group T19: `erikhfj`, `robertky`, `evenkkl`, +`rachelks`. + +| | | +| ----------------- | --------------------------------------- | +| Current milestone | **M1 - spec and mockup**, due 2 October | +| Live prototype | http://it2810-19.idi.ntnu.no/project2 | +| Workflow | [`docs/WORKFLOW.md`](docs/WORKFLOW.md) | +| AI usage log | [`docs/AI-USAGE.md`](docs/AI-USAGE.md) | + +## Getting started + +Requires Node.js 24+ and [pnpm](https://pnpm.io) 10+. + +```bash +pnpm install +pnpm dev # Vite dev server on :5173 +``` + +Before opening a PR: + +```bash +pnpm format:check && pnpm lint && pnpm typecheck && pnpm test +``` + +All four must pass. CI runs the same thing. + +| Command | Purpose | +| ----------------------------------- | ---------------------------------- | +| `pnpm dev` | Vite dev server | +| `pnpm build` | Type-check + production build | +| `pnpm lint` | ESLint - must pass with 0 warnings | +| `pnpm format` / `pnpm format:check` | Prettier | +| `pnpm typecheck` | `tsc --noEmit` in every workspace | +| `pnpm test` | Vitest, single run | + +## Project status + +| Milestone | Due | Delivers | +| --------- | ------ | ----------------------------------------------------------------------------------------- | +| M1 | 2 Oct | Spec and mockup: GraphQL schema, architecture ADRs, UI sketch, client rendering mock data | +| M2 | 16 Oct | PostgreSQL + GraphQL backend on the VM, client interaction | +| M3 | 30 Oct | Beta: search, paging, sorting, filtering, accessibility, bærekraft | +| M4 | 13 Nov | Finished prototype and the full test suite | + +`client/` currently renders mock data. `server/` (PostgreSQL + GraphQL Yoga) +arrives in M2 and `e2e/` (Playwright) in M4. + ## Working in this repository `main` is protected - you cannot push to it directly. Work on a branch and @@ -22,3 +74,6 @@ Before a pull request can be merged: 3. **Pushing new commits dismisses the approval**, so if you change something after being approved, ask for another review. This is deliberate: what was approved is what gets merged. + +Branch naming, commit style, PR size and review expectations are in +[`docs/WORKFLOW.md`](docs/WORKFLOW.md). diff --git a/docs/AI-USAGE.md b/docs/AI-USAGE.md new file mode 100644 index 0000000..b395bd7 --- /dev/null +++ b/docs/AI-USAGE.md @@ -0,0 +1,85 @@ +# AI usage log + +IT2810 requires documentation of how AI tools were used, and — more +importantly — evidence that the group exercises its own control and planning +over the development. That evidence lives in the issues, the pull requests and +the reviews. This file is the connective tissue: it records, **per PR**, what +we asked for, what we accepted, what we changed or rejected and why, and what +a reviewer pushed back on. + +## Format + +One entry per PR, appended as work lands: + +```md +### PR #N — + +- **Asked for:** … +- **Took:** … +- **Changed / rejected and why:** … +- **Reviewer pushed back on:** … +- **Can defend line by line:** … +``` + +The last line matters. If the author cannot explain a piece of the diff in a +viva, it does not belong in the PR. + +## Tools in use + +| Tool | Used for | +| ----------------------- | ------------------------------------------------------------------ | +| opencode (CLI agent) | Scaffolding, drafting, running the quality gates, deploy scripting | +| GitHub Copilot (editor) | Autocomplete while writing components and tests | +| Playwright MCP | Manual exploration while writing end-to-end tests | +| Context7 MCP | Checking current library APIs rather than relying on training data | + +## Log + +### 2026-09-24 — process: retiring the scaffold prototype + +- **Asked for:** a plan for how to restructure the project after the group + objected to a single large PR. +- **Took:** the diagnosis and the milestone pacing. The group corrected two + things and those corrections are the important part of this entry: + 1. **Rachel:** splitting the generated code into smaller PRs would only fix + the git cosmetics. Each issue must be implemented from its requirements, + by its owner. The prototype is a reference, not a source to copy from. + 2. **Robert:** a formal "plan in the issue before coding" step was process + for its own sake. Clear issues plus small PRs that say what was done and + tested is what a reviewer actually reads. +- **Changed / rejected:** dropped the mandatory pre-coding plan comment from + all five M1 issues and replaced it with two lines: implement from the + requirement, and describe what was done and tested in the PR. Also dropped + assigning all 30 issues up front — issues are now assigned one milestone at + a time, per Robert. +- **Outcome:** PR #31 closed unmerged. The branch lives on as + [`archive/scaffold-prototype`](../../tree/archive/scaffold-prototype). It + was useful for answering "does Postgres FTS give us case-insensitive + single-term search?" and "can cursor pagination stay correct across every + sort mode?" early — those were real design risks. It is not the deliverable, + and the code in it is not what we are graded on. + +### 2026-09-23 — scaffold prototype (now archived, never merged) + +Recorded here because it happened and hiding it would defeat the purpose. + +- **Asked for:** the full stack to be configured so the group could start + working — GraphQL Yoga + Drizzle + PostgreSQL backend, React + Apollo + client, Vitest and Playwright, docs, and a deploy to the group VM. +- **Took:** a working implementation that was verified live on the VM (search, + facets, cursor paging, sorting, review and crate mutations, nested detail). +- **Changed / rejected:** three bugs the smoke suite caught that the unit + tests had missed — `GenreFacet.genre` shape drift from the SDL, drizzle + expanding a JS array into scalar parameters inside a `::int[]` cast, and a + missing review aggregate on `album(id:)`. All three were fixed and + regression-tested. `SEARCH_ALBUMS` also referenced `$userId` without + declaring it in the operation signature. +- **Lesson recorded:** unit tests over SQL _builders_ are necessary but not + sufficient. Nothing in that suite ever executed a query against Postgres, + which is exactly where all three bugs lived. Hit the running API before + calling a backend change done. +- **Status:** closed unmerged. See the entry above. + +--- + +_Append new entries above this line, newest first._ diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md new file mode 100644 index 0000000..98d5c64 --- /dev/null +++ b/docs/WORKFLOW.md @@ -0,0 +1,82 @@ +# Workflow + +How we work in this repository. Agreed by the group, 24 September 2026. + +## Branching + +``` +feat/<issue>-short-name new functionality +fix/<issue>-short-name bug fixes +docs/<issue>-short-name documentation +chore/<issue>-short-name tooling, dependencies, CI +``` + +Branch from `main`. Keep the branch name tied to the issue so the history +reads as a list of the work we planned. + +## Commits + +Conventional commits, referencing the issue: + +``` +feat: #9 mock-data search list with debounced input +fix: #13 facet counts ignored the active genre filter +chore: #1 pnpm workspace, ESLint, Prettier, TypeScript +``` + +One logical change per commit. If a change needs three paragraphs to explain, +it should probably have been two commits. + +## Pull requests + +- **Small.** Reviewable in about 30 minutes. If it touches more than a dozen + files, it should have been split. +- **One owner, one reviewer who is not the author.** Rotating who reviews + which area is the point — we learn from each other's code. +- **The description says what was done and what was tested.** That is what the + reviewer reads. Include the commands you ran and their output if the change + is behavioural. +- A review with only "LGTM" is not a review. Ask a question, push back on + something, or point at an alternative. Even when the answer is "you're + right, no change needed", it shows we engaged. + +`main` is protected: no direct pushes. Every change goes through a PR and an +approval from `@IT2810-H26/it2810-h26-t19`. Staff approvals do not count. + +## Before opening a PR + +Implement from the issue's requirements — not by copying from +`archive/scaffold-prototype`. That branch is a reference to check against or +to consult when stuck, not a source to paste from. + +Then run: + +```bash +pnpm format:check && pnpm lint && pnpm typecheck && pnpm test +``` + +All four must pass. CI runs the same thing and will reject the PR otherwise. + +## Milestones + +Work is planned in four milestones that line up with the four +underveisinnleveringer. Issues are assigned one milestone at a time — at the +start of each milestone, not all at once up front — so we can rebalance based +on what we learned from the previous one. + +| Milestone | Due | Delivers | +| --------- | ------ | ------------------------------------------------------------------ | +| M1 | 2 Oct | Spec and mockup: schema, ADRs, UI sketch, client with mock data | +| M2 | 16 Oct | Database and GraphQL backend running on the VM, client interaction | +| M3 | 30 Oct | Beta: search, paging, sorting, filtering, accessibility, bærekraft | +| M4 | 13 Nov | Finished prototype and the full test suite | + +## Using AI tools + +AI is allowed and we use it. What the course requires is that we document how, +and that the process shows our own control and planning through issues, pull +requests, code review and systematic collaboration. + +That is what [`docs/AI-USAGE.md`](./AI-USAGE.md) is for: a **decision log per +PR** — what we asked for, what we took, what we changed or rejected and why, +and what the reviewer pushed back on. Not a list of tools used. From 168d2df35d2d0fdd8e555bb95beb904053639611 Mon Sep 17 00:00:00 2001 From: Erik Hjelm Fjeldheim <erikhfj@stud.ntnu.no> Date: Fri, 25 Sep 2026 12:48:49 -0600 Subject: [PATCH 2/8] docs: #4 replace em-dashes with hyphens House style is plain hyphens. No functional change. Co-Authored-By: opencode <noreply@opencode.ai> --- docs/AI-USAGE.md | 18 +++++++++--------- docs/WORKFLOW.md | 10 +++++----- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/AI-USAGE.md b/docs/AI-USAGE.md index b395bd7..beba80a 100644 --- a/docs/AI-USAGE.md +++ b/docs/AI-USAGE.md @@ -1,7 +1,7 @@ # AI usage log -IT2810 requires documentation of how AI tools were used, and — more -importantly — evidence that the group exercises its own control and planning +IT2810 requires documentation of how AI tools were used, and - more +importantly - evidence that the group exercises its own control and planning over the development. That evidence lives in the issues, the pull requests and the reviews. This file is the connective tissue: it records, **per PR**, what we asked for, what we accepted, what we changed or rejected and why, and what @@ -12,7 +12,7 @@ a reviewer pushed back on. One entry per PR, appended as work lands: ```md -### PR #N — <title> +### PR #N - <title> - **Asked for:** … - **Took:** … @@ -35,7 +35,7 @@ viva, it does not belong in the PR. ## Log -### 2026-09-24 — process: retiring the scaffold prototype +### 2026-09-24 - process: retiring the scaffold prototype - **Asked for:** a plan for how to restructure the project after the group objected to a single large PR. @@ -50,26 +50,26 @@ viva, it does not belong in the PR. - **Changed / rejected:** dropped the mandatory pre-coding plan comment from all five M1 issues and replaced it with two lines: implement from the requirement, and describe what was done and tested in the PR. Also dropped - assigning all 30 issues up front — issues are now assigned one milestone at + assigning all 30 issues up front - issues are now assigned one milestone at a time, per Robert. - **Outcome:** PR #31 closed unmerged. The branch lives on as [`archive/scaffold-prototype`](../../tree/archive/scaffold-prototype). It was useful for answering "does Postgres FTS give us case-insensitive single-term search?" and "can cursor pagination stay correct across every - sort mode?" early — those were real design risks. It is not the deliverable, + sort mode?" early - those were real design risks. It is not the deliverable, and the code in it is not what we are graded on. -### 2026-09-23 — scaffold prototype (now archived, never merged) +### 2026-09-23 - scaffold prototype (now archived, never merged) Recorded here because it happened and hiding it would defeat the purpose. - **Asked for:** the full stack to be configured so the group could start - working — GraphQL Yoga + Drizzle + PostgreSQL backend, React + Apollo + working - GraphQL Yoga + Drizzle + PostgreSQL backend, React + Apollo client, Vitest and Playwright, docs, and a deploy to the group VM. - **Took:** a working implementation that was verified live on the VM (search, facets, cursor paging, sorting, review and crate mutations, nested detail). - **Changed / rejected:** three bugs the smoke suite caught that the unit - tests had missed — `GenreFacet.genre` shape drift from the SDL, drizzle + tests had missed - `GenreFacet.genre` shape drift from the SDL, drizzle expanding a JS array into scalar parameters inside a `::int[]` cast, and a missing review aggregate on `album(id:)`. All three were fixed and regression-tested. `SEARCH_ALBUMS` also referenced `$userId` without diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md index 98d5c64..9e6af43 100644 --- a/docs/WORKFLOW.md +++ b/docs/WORKFLOW.md @@ -32,7 +32,7 @@ it should probably have been two commits. - **Small.** Reviewable in about 30 minutes. If it touches more than a dozen files, it should have been split. - **One owner, one reviewer who is not the author.** Rotating who reviews - which area is the point — we learn from each other's code. + which area is the point - we learn from each other's code. - **The description says what was done and what was tested.** That is what the reviewer reads. Include the commands you ran and their output if the change is behavioural. @@ -45,7 +45,7 @@ approval from `@IT2810-H26/it2810-h26-t19`. Staff approvals do not count. ## Before opening a PR -Implement from the issue's requirements — not by copying from +Implement from the issue's requirements - not by copying from `archive/scaffold-prototype`. That branch is a reference to check against or to consult when stuck, not a source to paste from. @@ -60,8 +60,8 @@ All four must pass. CI runs the same thing and will reject the PR otherwise. ## Milestones Work is planned in four milestones that line up with the four -underveisinnleveringer. Issues are assigned one milestone at a time — at the -start of each milestone, not all at once up front — so we can rebalance based +underveisinnleveringer. Issues are assigned one milestone at a time - at the +start of each milestone, not all at once up front - so we can rebalance based on what we learned from the previous one. | Milestone | Due | Delivers | @@ -78,5 +78,5 @@ and that the process shows our own control and planning through issues, pull requests, code review and systematic collaboration. That is what [`docs/AI-USAGE.md`](./AI-USAGE.md) is for: a **decision log per -PR** — what we asked for, what we took, what we changed or rejected and why, +PR** - what we asked for, what we took, what we changed or rejected and why, and what the reviewer pushed back on. Not a list of tools used. From 57df1b9bfbe14bfc7e3ba066237bae9bc384f86d Mon Sep 17 00:00:00 2001 From: Erik Hjelm Fjeldheim <erikhfj@stud.ntnu.no> Date: Thu, 1 Oct 2026 13:30:37 -0600 Subject: [PATCH 3/8] docs: #4 soften the review rule to guidance Robert's position on process is that clear issues plus small PRs with a good description of what was done and tested is what matters. The original wording turned that into a gate ("LGTM is not a review, ask a question"), which is the same species of overhead as the plan-before-code step we already dropped. Reworded so the intent survives and the mandate does not. Trivial changes may simply be approved. Co-Authored-By: opencode <noreply@opencode.ai> --- docs/WORKFLOW.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md index 9e6af43..d297df8 100644 --- a/docs/WORKFLOW.md +++ b/docs/WORKFLOW.md @@ -36,9 +36,11 @@ it should probably have been two commits. - **The description says what was done and what was tested.** That is what the reviewer reads. Include the commands you ran and their output if the change is behavioural. -- A review with only "LGTM" is not a review. Ask a question, push back on - something, or point at an alternative. Even when the answer is "you're - right, no change needed", it shows we engaged. +- **"LGTM" on its own is a weak review.** A question or a push-back is usually + worth more than an approval, even when the answer turns out to be "you're + right, no change needed". This is guidance, not a gate: if a change really is + trivial, approving it is fine. The course asks us to learn from each other's + code, and that is what this is for. `main` is protected: no direct pushes. Every change goes through a PR and an approval from `@IT2810-H26/it2810-h26-t19`. Staff approvals do not count. From 582c450456ea104b6261ea38d05c3a8e62353347 Mon Sep 17 00:00:00 2001 From: Erik Hjelm Fjeldheim <erikhfj@stud.ntnu.no> Date: Thu, 1 Oct 2026 13:53:58 -0600 Subject: [PATCH 4/8] docs: #4 simplify the AI usage log to a table Replaced the prose decision log with a four column table: Date, Who, Tool, Used for. The narrative entries were long enough that nobody was going to read them, and the course requirement is documentation of how the tools were used. What survives in the table is what was actually used for, including the bugs the smoke tests and the code review caught. Two rows have a dash in the Tool column on purpose. Rachel overruled the plan to split the generated code into smaller PRs, and Robert overruled the plan-before-code step. Those are the rows that show our own control rather than just tool usage, so they belong in the same table rather than in a separate note. Left empty rows for robertky, evenkkl and rachelks to fill in. Updated WORKFLOW.md to describe the table instead of the old format. Co-Authored-By: opencode <noreply@opencode.ai> --- docs/AI-USAGE.md | 119 ++++++++++++++--------------------------------- docs/WORKFLOW.md | 7 +-- 2 files changed, 40 insertions(+), 86 deletions(-) diff --git a/docs/AI-USAGE.md b/docs/AI-USAGE.md index beba80a..0632cff 100644 --- a/docs/AI-USAGE.md +++ b/docs/AI-USAGE.md @@ -1,85 +1,38 @@ # AI usage log -IT2810 requires documentation of how AI tools were used, and - more -importantly - evidence that the group exercises its own control and planning -over the development. That evidence lives in the issues, the pull requests and -the reviews. This file is the connective tissue: it records, **per PR**, what -we asked for, what we accepted, what we changed or rejected and why, and what -a reviewer pushed back on. - -## Format - -One entry per PR, appended as work lands: - -```md -### PR #N - <title> - -- **Asked for:** … -- **Took:** … -- **Changed / rejected and why:** … -- **Reviewer pushed back on:** … -- **Can defend line by line:** … -``` - -The last line matters. If the author cannot explain a piece of the diff in a -viva, it does not belong in the PR. - -## Tools in use - -| Tool | Used for | -| ----------------------- | ------------------------------------------------------------------ | -| opencode (CLI agent) | Scaffolding, drafting, running the quality gates, deploy scripting | -| GitHub Copilot (editor) | Autocomplete while writing components and tests | -| Playwright MCP | Manual exploration while writing end-to-end tests | -| Context7 MCP | Checking current library APIs rather than relying on training data | - -## Log - -### 2026-09-24 - process: retiring the scaffold prototype - -- **Asked for:** a plan for how to restructure the project after the group - objected to a single large PR. -- **Took:** the diagnosis and the milestone pacing. The group corrected two - things and those corrections are the important part of this entry: - 1. **Rachel:** splitting the generated code into smaller PRs would only fix - the git cosmetics. Each issue must be implemented from its requirements, - by its owner. The prototype is a reference, not a source to copy from. - 2. **Robert:** a formal "plan in the issue before coding" step was process - for its own sake. Clear issues plus small PRs that say what was done and - tested is what a reviewer actually reads. -- **Changed / rejected:** dropped the mandatory pre-coding plan comment from - all five M1 issues and replaced it with two lines: implement from the - requirement, and describe what was done and tested in the PR. Also dropped - assigning all 30 issues up front - issues are now assigned one milestone at - a time, per Robert. -- **Outcome:** PR #31 closed unmerged. The branch lives on as - [`archive/scaffold-prototype`](../../tree/archive/scaffold-prototype). It - was useful for answering "does Postgres FTS give us case-insensitive - single-term search?" and "can cursor pagination stay correct across every - sort mode?" early - those were real design risks. It is not the deliverable, - and the code in it is not what we are graded on. - -### 2026-09-23 - scaffold prototype (now archived, never merged) - -Recorded here because it happened and hiding it would defeat the purpose. - -- **Asked for:** the full stack to be configured so the group could start - working - GraphQL Yoga + Drizzle + PostgreSQL backend, React + Apollo - client, Vitest and Playwright, docs, and a deploy to the group VM. -- **Took:** a working implementation that was verified live on the VM (search, - facets, cursor paging, sorting, review and crate mutations, nested detail). -- **Changed / rejected:** three bugs the smoke suite caught that the unit - tests had missed - `GenreFacet.genre` shape drift from the SDL, drizzle - expanding a JS array into scalar parameters inside a `::int[]` cast, and a - missing review aggregate on `album(id:)`. All three were fixed and - regression-tested. `SEARCH_ALBUMS` also referenced `$userId` without - declaring it in the operation signature. -- **Lesson recorded:** unit tests over SQL _builders_ are necessary but not - sufficient. Nothing in that suite ever executed a query against Postgres, - which is exactly where all three bugs lived. Hit the running API before - calling a backend change done. -- **Status:** closed unmerged. See the entry above. - ---- - -_Append new entries above this line, newest first._ +IT2810 requires documentation of how AI tools were used, and that the group +shows its own control over the development. The control is visible in the +issues, the pull requests and the reviews. This table is the record of tool +usage behind that work. + +Everyone adds their own rows. Two rows in the middle have no tool in them on +purpose: they are where a person overruled what the tool proposed, which is +the part that matters most. + +| Date | Who | Tool | Used for | +| ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 2026-09-23 | erikhfj | opencode | Stack prototype (PostgreSQL, GraphQL Yoga, Drizzle, React + Apollo) to answer two design risks early: does Postgres FTS give case-insensitive single-term search, and does keyset paging stay correct across every sort mode. Verified live on the VM. **Closed unmerged**, kept as `archive/scaffold-prototype`. | +| 2026-09-23 | erikhfj | opencode | VM bootstrap scripts: PostgreSQL role and database, Node 24 via nvm, `crate-api` systemd unit, Apache `ProxyPass /graphql` | +| 2026-09-23 | erikhfj | opencode | Smoke tests against the running API. These caught three bugs the unit tests had missed: `GenreFacet.genre` shape drift from the SDL, drizzle expanding a JS array into scalar parameters inside a `::int[]` cast, and a missing review aggregate on `album(id:)` | +| 2026-09-24 | erikhfj | opencode | Plan to retire the prototype PR and re-land the work in milestone-sized PRs | +| 2026-09-24 | rachelks | - | **Overruled the plan.** Splitting generated code into smaller PRs would only fix the git cosmetics, so each issue must be implemented from its requirements by its owner. The prototype is a reference, not a source to copy from. Taken. | +| 2026-09-24 | robertky | - | **Overruled the plan.** Dropped the plan-before-code step as process for its own sake; clear issues plus PR descriptions that say what was done and tested are what reviewers read. Also: assign issues one milestone at a time, not all up front. Taken. | +| 2026-09-28 | erikhfj | opencode | Tooling for #1: pnpm workspace, ESLint 9 flat config, Prettier, strict TypeScript, `AGENTS.md` | +| 2026-09-28 | erikhfj | opencode | Review fix for #1: `.gitattributes` with `* text=auto eol=lf` after `core.autocrlf` broke `pnpm format:check` on Windows | +| 2026-09-28 | erikhfj | opencode | Workflow guide and this log for #4 | +| 2026-09-28 | erikhfj | opencode | CI for #27: `quality` and `deploy` jobs, self-hosted runner registered on the VM, client bundle budget | +| 2026-09-29 | erikhfj | opencode | Review fix for #27: `pull_request` no longer filters on `branches: [main]`, which had silently given stacked PRs zero CI runs | +| 2026-10-01 | erikhfj | opencode | Answers to the open design questions: UUID as an `X-User-Id` header into the GraphQL context, narrowing facet counts, `id` tie-breakers, nulls last in both directions | +| 2026-10-01 | erikhfj | opencode | CI deploy fix for #27 after rachelks reported it: `grep -q` SIGPIPE silently skipped a live service, `sudo` had no TTY, and `sleep 2` raced Node binding the port. All three verified against the live unit | +| 2026-10-01 | erikhfj | opencode | Simplified this log to a table at the group's request | +| | robertky | - | _add your rows here_ | +| | evenkkl | - | _add your rows here_ | +| | rachelks | - | _add your rows here_ | + +## Notes + +- The prototype was never merged. `archive/scaffold-prototype` is a reference to + check against or to consult when stuck, not a source to copy from. That was + Rachel's correction and it is the rule the rest of this table follows. +- Anything in a PR that the author cannot explain line by line should not be in + the PR. That is the test, not the tool that produced it. diff --git a/docs/WORKFLOW.md b/docs/WORKFLOW.md index d297df8..1a4a7d4 100644 --- a/docs/WORKFLOW.md +++ b/docs/WORKFLOW.md @@ -79,6 +79,7 @@ AI is allowed and we use it. What the course requires is that we document how, and that the process shows our own control and planning through issues, pull requests, code review and systematic collaboration. -That is what [`docs/AI-USAGE.md`](./AI-USAGE.md) is for: a **decision log per -PR** - what we asked for, what we took, what we changed or rejected and why, -and what the reviewer pushed back on. Not a list of tools used. +That is what [`docs/AI-USAGE.md`](./AI-USAGE.md) is for: a table of date, who, +tool and what it was used for. Everyone adds their own rows. The rows with no +tool in them are the ones where a person overruled the tool, which is the +evidence of our own control that the course actually asks for. From a0392eaab5710181f663ff5c3ea43481082b8a25 Mon Sep 17 00:00:00 2001 From: Robert Andreas Kyllo <robertky@stud.ntnu.no> Date: Fri, 2 Oct 2026 13:55:29 +0200 Subject: [PATCH 5/8] docs: #4 add Robert's AI usage --- docs/AI-USAGE.md | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/AI-USAGE.md b/docs/AI-USAGE.md index 0632cff..4c409f7 100644 --- a/docs/AI-USAGE.md +++ b/docs/AI-USAGE.md @@ -9,25 +9,27 @@ Everyone adds their own rows. Two rows in the middle have no tool in them on purpose: they are where a person overruled what the tool proposed, which is the part that matters most. -| Date | Who | Tool | Used for | -| ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 2026-09-23 | erikhfj | opencode | Stack prototype (PostgreSQL, GraphQL Yoga, Drizzle, React + Apollo) to answer two design risks early: does Postgres FTS give case-insensitive single-term search, and does keyset paging stay correct across every sort mode. Verified live on the VM. **Closed unmerged**, kept as `archive/scaffold-prototype`. | -| 2026-09-23 | erikhfj | opencode | VM bootstrap scripts: PostgreSQL role and database, Node 24 via nvm, `crate-api` systemd unit, Apache `ProxyPass /graphql` | -| 2026-09-23 | erikhfj | opencode | Smoke tests against the running API. These caught three bugs the unit tests had missed: `GenreFacet.genre` shape drift from the SDL, drizzle expanding a JS array into scalar parameters inside a `::int[]` cast, and a missing review aggregate on `album(id:)` | -| 2026-09-24 | erikhfj | opencode | Plan to retire the prototype PR and re-land the work in milestone-sized PRs | -| 2026-09-24 | rachelks | - | **Overruled the plan.** Splitting generated code into smaller PRs would only fix the git cosmetics, so each issue must be implemented from its requirements by its owner. The prototype is a reference, not a source to copy from. Taken. | -| 2026-09-24 | robertky | - | **Overruled the plan.** Dropped the plan-before-code step as process for its own sake; clear issues plus PR descriptions that say what was done and tested are what reviewers read. Also: assign issues one milestone at a time, not all up front. Taken. | -| 2026-09-28 | erikhfj | opencode | Tooling for #1: pnpm workspace, ESLint 9 flat config, Prettier, strict TypeScript, `AGENTS.md` | -| 2026-09-28 | erikhfj | opencode | Review fix for #1: `.gitattributes` with `* text=auto eol=lf` after `core.autocrlf` broke `pnpm format:check` on Windows | -| 2026-09-28 | erikhfj | opencode | Workflow guide and this log for #4 | -| 2026-09-28 | erikhfj | opencode | CI for #27: `quality` and `deploy` jobs, self-hosted runner registered on the VM, client bundle budget | -| 2026-09-29 | erikhfj | opencode | Review fix for #27: `pull_request` no longer filters on `branches: [main]`, which had silently given stacked PRs zero CI runs | -| 2026-10-01 | erikhfj | opencode | Answers to the open design questions: UUID as an `X-User-Id` header into the GraphQL context, narrowing facet counts, `id` tie-breakers, nulls last in both directions | -| 2026-10-01 | erikhfj | opencode | CI deploy fix for #27 after rachelks reported it: `grep -q` SIGPIPE silently skipped a live service, `sudo` had no TTY, and `sleep 2` raced Node binding the port. All three verified against the live unit | -| 2026-10-01 | erikhfj | opencode | Simplified this log to a table at the group's request | -| | robertky | - | _add your rows here_ | -| | evenkkl | - | _add your rows here_ | -| | rachelks | - | _add your rows here_ | +| Date | Who | Tool | Used for | +| ---------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 2026-09-23 | erikhfj | opencode | Stack prototype (PostgreSQL, GraphQL Yoga, Drizzle, React + Apollo) to answer two design risks early: does Postgres FTS give case-insensitive single-term search, and does keyset paging stay correct across every sort mode. Verified live on the VM. **Closed unmerged**, kept as `archive/scaffold-prototype`. | +| 2026-09-23 | erikhfj | opencode | VM bootstrap scripts: PostgreSQL role and database, Node 24 via nvm, `crate-api` systemd unit, Apache `ProxyPass /graphql` | +| 2026-09-23 | erikhfj | opencode | Smoke tests against the running API. These caught three bugs the unit tests had missed: `GenreFacet.genre` shape drift from the SDL, drizzle expanding a JS array into scalar parameters inside a `::int[]` cast, and a missing review aggregate on `album(id:)` | +| 2026-09-24 | erikhfj | opencode | Plan to retire the prototype PR and re-land the work in milestone-sized PRs | +| 2026-09-24 | rachelks | - | **Overruled the plan.** Splitting generated code into smaller PRs would only fix the git cosmetics, so each issue must be implemented from its requirements by its owner. The prototype is a reference, not a source to copy from. Taken. | +| 2026-09-24 | robertky | - | **Overruled the plan.** Dropped the plan-before-code step as process for its own sake; clear issues plus PR descriptions that say what was done and tested are what reviewers read. Also: assign issues one milestone at a time, not all up front. Taken. | +| 2026-09-28 | erikhfj | opencode | Tooling for #1: pnpm workspace, ESLint 9 flat config, Prettier, strict TypeScript, `AGENTS.md` | +| 2026-09-28 | erikhfj | opencode | Review fix for #1: `.gitattributes` with `* text=auto eol=lf` after `core.autocrlf` broke `pnpm format:check` on Windows | +| 2026-09-28 | erikhfj | opencode | Workflow guide and this log for #4 | +| 2026-09-28 | erikhfj | opencode | CI for #27: `quality` and `deploy` jobs, self-hosted runner registered on the VM, client bundle budget | +| 2026-09-29 | erikhfj | opencode | Review fix for #27: `pull_request` no longer filters on `branches: [main]`, which had silently given stacked PRs zero CI runs | +| 2026-10-01 | erikhfj | opencode | Answers to the open design questions: UUID as an `X-User-Id` header into the GraphQL context, narrowing facet counts, `id` tie-breakers, nulls last in both directions | +| 2026-10-01 | erikhfj | opencode | CI deploy fix for #27 after rachelks reported it: `grep -q` SIGPIPE silently skipped a live service, `sudo` had no TTY, and `sleep 2` raced Node binding the port. All three verified against the live unit | +| 2026-10-01 | erikhfj | opencode | Simplified this log to a table at the group's request | +| 2026-09-27 | robertky | Codex (ChatGPT) | Assisted with drafting the M1 GraphQL schema and data model for #2. I reviewed the model, kept database/resolvers out of M1, and incorporated peer-review feedback before merge. | +| 2026-09-30 | robertky | Codex (ChatGPT) | Helped me interpret Rachel's schema review on #35. | +| 2026-10-01 | robertky | Codex (ChatGPT) | Assisted with formulating good reviews of the architecture and UI-specification PRs. The group decided to include decade filtering; Rachel implemented the corresponding schema and documentation update in #38. | +| | evenkkl | - | _add your rows here_ | +| | rachelks | - | _add your rows here_ | ## Notes From d8e891274354466585ff8a8c91a7b6f7bf4ed822 Mon Sep 17 00:00:00 2001 From: Rachel Knutsen Stiansen <rachelks@stud.ntnu.no> Date: Fri, 2 Oct 2026 14:45:22 +0200 Subject: [PATCH 6/8] docs: #4 add Rachel's AI usage and sort entries by date --- docs/AI-USAGE.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/AI-USAGE.md b/docs/AI-USAGE.md index 4c409f7..968b23c 100644 --- a/docs/AI-USAGE.md +++ b/docs/AI-USAGE.md @@ -17,19 +17,23 @@ the part that matters most. | 2026-09-24 | erikhfj | opencode | Plan to retire the prototype PR and re-land the work in milestone-sized PRs | | 2026-09-24 | rachelks | - | **Overruled the plan.** Splitting generated code into smaller PRs would only fix the git cosmetics, so each issue must be implemented from its requirements by its owner. The prototype is a reference, not a source to copy from. Taken. | | 2026-09-24 | robertky | - | **Overruled the plan.** Dropped the plan-before-code step as process for its own sake; clear issues plus PR descriptions that say what was done and tested are what reviewers read. Also: assign issues one milestone at a time, not all up front. Taken. | +| 2026-09-27 | rachelks | Codex (ChatGPT) | Discussed the UI specification for #29 and how to translate the project requirements into the planned interface. I reviewed and adapted the specification to the group's agreed design. | +| 2026-09-27 | robertky | Codex (ChatGPT) | Assisted with drafting the M1 GraphQL schema and data model for #2. I reviewed the model, kept database/resolvers out of M1, and incorporated peer-review feedback before merge. | | 2026-09-28 | erikhfj | opencode | Tooling for #1: pnpm workspace, ESLint 9 flat config, Prettier, strict TypeScript, `AGENTS.md` | +| 2026-09-28 | rachelks | Codex (ChatGPT) | Assisted with reviewing #32 and diagnosing a Windows-specific formatting failure. Testing with `core.autocrlf=true` exposed the LF/CRLF issue; I reported it in the review and erikhfj fixed it with `.gitattributes` before merge. | | 2026-09-28 | erikhfj | opencode | Review fix for #1: `.gitattributes` with `* text=auto eol=lf` after `core.autocrlf` broke `pnpm format:check` on Windows | | 2026-09-28 | erikhfj | opencode | Workflow guide and this log for #4 | | 2026-09-28 | erikhfj | opencode | CI for #27: `quality` and `deploy` jobs, self-hosted runner registered on the VM, client bundle budget | +| 2026-09-28 | rachelks | Codex (ChatGPT) | Assisted with reviewing the CI workflow in #34. Identified that the `project2` runner label was not used by the deploy job. I reported it in the review, erikhfj then pinned the deploy job to the intended runner. | | 2026-09-29 | erikhfj | opencode | Review fix for #27: `pull_request` no longer filters on `branches: [main]`, which had silently given stacked PRs zero CI runs | +| 2026-09-30 | rachelks | Codex (ChatGPT) | Assisted with reviewing the GraphQL schema in #35. I identified a missing paginated review connection required by the specification and requested changes; robertky corrected the schema before merge. | +| 2026-09-30 | robertky | Codex (ChatGPT) | Helped me interpret Rachel's schema review on #35. | | 2026-10-01 | erikhfj | opencode | Answers to the open design questions: UUID as an `X-User-Id` header into the GraphQL context, narrowing facet counts, `id` tie-breakers, nulls last in both directions | +| 2026-10-01 | rachelks | Codex (ChatGPT) | Assisted with diagnosing the CI deploy failure after merge. The investigation traced the API restart issue to the `crate-api.service` check, `sudo` requiring a TTY, and a race while waiting for the API to start; erikhfj then fixed the deploy workflow. | | 2026-10-01 | erikhfj | opencode | CI deploy fix for #27 after rachelks reported it: `grep -q` SIGPIPE silently skipped a live service, `sudo` had no TTY, and `sleep 2` raced Node binding the port. All three verified against the live unit | | 2026-10-01 | erikhfj | opencode | Simplified this log to a table at the group's request | -| 2026-09-27 | robertky | Codex (ChatGPT) | Assisted with drafting the M1 GraphQL schema and data model for #2. I reviewed the model, kept database/resolvers out of M1, and incorporated peer-review feedback before merge. | -| 2026-09-30 | robertky | Codex (ChatGPT) | Helped me interpret Rachel's schema review on #35. | | 2026-10-01 | robertky | Codex (ChatGPT) | Assisted with formulating good reviews of the architecture and UI-specification PRs. The group decided to include decade filtering; Rachel implemented the corresponding schema and documentation update in #38. | | | evenkkl | - | _add your rows here_ | -| | rachelks | - | _add your rows here_ | ## Notes From cbfff7528e2a1ffbddfd3350c4d2972adc9e5ce5 Mon Sep 17 00:00:00 2001 From: Even <evenkkl@stud.ntnu.no> Date: Fri, 2 Oct 2026 15:45:17 +0200 Subject: [PATCH 7/8] docs: Added AI-Usage documentation Provided documentation on AI usage for Even --- docs/AI-USAGE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/AI-USAGE.md b/docs/AI-USAGE.md index 968b23c..8be5ab2 100644 --- a/docs/AI-USAGE.md +++ b/docs/AI-USAGE.md @@ -33,8 +33,8 @@ the part that matters most. | 2026-10-01 | erikhfj | opencode | CI deploy fix for #27 after rachelks reported it: `grep -q` SIGPIPE silently skipped a live service, `sudo` had no TTY, and `sleep 2` raced Node binding the port. All three verified against the live unit | | 2026-10-01 | erikhfj | opencode | Simplified this log to a table at the group's request | | 2026-10-01 | robertky | Codex (ChatGPT) | Assisted with formulating good reviews of the architecture and UI-specification PRs. The group decided to include decade filtering; Rachel implemented the corresponding schema and documentation update in #38. | -| | evenkkl | - | _add your rows here_ | - +| 2026-09-28 | evenkkl | Claude | Assisted with formulating a schema for the Architecture decision in PR#36, and was a sparring partner to help understand why we should make the decisions we did. | +| 2026-09-30 | evenkkl | Claude | Assisted with formulating good reviews of PR#35, and find improvements one didnt catch on their own. ## Notes - The prototype was never merged. `archive/scaffold-prototype` is a reference to From c4bc766a2fadaf9a35f9522d5160041c755e58c1 Mon Sep 17 00:00:00 2001 From: Rachel Knutsen Stiansen <rachelks@stud.ntnu.no> Date: Fri, 2 Oct 2026 16:23:56 +0200 Subject: [PATCH 8/8] docs: #4 sort and format AI usage log --- docs/AI-USAGE.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/AI-USAGE.md b/docs/AI-USAGE.md index 8be5ab2..321d7e7 100644 --- a/docs/AI-USAGE.md +++ b/docs/AI-USAGE.md @@ -17,24 +17,25 @@ the part that matters most. | 2026-09-24 | erikhfj | opencode | Plan to retire the prototype PR and re-land the work in milestone-sized PRs | | 2026-09-24 | rachelks | - | **Overruled the plan.** Splitting generated code into smaller PRs would only fix the git cosmetics, so each issue must be implemented from its requirements by its owner. The prototype is a reference, not a source to copy from. Taken. | | 2026-09-24 | robertky | - | **Overruled the plan.** Dropped the plan-before-code step as process for its own sake; clear issues plus PR descriptions that say what was done and tested are what reviewers read. Also: assign issues one milestone at a time, not all up front. Taken. | -| 2026-09-27 | rachelks | Codex (ChatGPT) | Discussed the UI specification for #29 and how to translate the project requirements into the planned interface. I reviewed and adapted the specification to the group's agreed design. | +| 2026-09-27 | rachelks | Codex (ChatGPT) | Discussed the UI specification for #29 and how to translate the project requirements into the planned interface. I reviewed and adapted the specification to the group's agreed design. | | 2026-09-27 | robertky | Codex (ChatGPT) | Assisted with drafting the M1 GraphQL schema and data model for #2. I reviewed the model, kept database/resolvers out of M1, and incorporated peer-review feedback before merge. | | 2026-09-28 | erikhfj | opencode | Tooling for #1: pnpm workspace, ESLint 9 flat config, Prettier, strict TypeScript, `AGENTS.md` | -| 2026-09-28 | rachelks | Codex (ChatGPT) | Assisted with reviewing #32 and diagnosing a Windows-specific formatting failure. Testing with `core.autocrlf=true` exposed the LF/CRLF issue; I reported it in the review and erikhfj fixed it with `.gitattributes` before merge. | +| 2026-09-28 | rachelks | Codex (ChatGPT) | Assisted with reviewing #32 and diagnosing a Windows-specific formatting failure. Testing with `core.autocrlf=true` exposed the LF/CRLF issue; I reported it in the review and erikhfj fixed it with `.gitattributes` before merge. | | 2026-09-28 | erikhfj | opencode | Review fix for #1: `.gitattributes` with `* text=auto eol=lf` after `core.autocrlf` broke `pnpm format:check` on Windows | | 2026-09-28 | erikhfj | opencode | Workflow guide and this log for #4 | +| 2026-09-28 | evenkkl | Claude | Assisted with formulating a schema for the architecture decision in #3, and served as a sparring partner to help understand why we made the decisions we did. | | 2026-09-28 | erikhfj | opencode | CI for #27: `quality` and `deploy` jobs, self-hosted runner registered on the VM, client bundle budget | -| 2026-09-28 | rachelks | Codex (ChatGPT) | Assisted with reviewing the CI workflow in #34. Identified that the `project2` runner label was not used by the deploy job. I reported it in the review, erikhfj then pinned the deploy job to the intended runner. | +| 2026-09-28 | rachelks | Codex (ChatGPT) | Assisted with reviewing the CI workflow in #34. Identified that the `project2` runner label was not used by the deploy job. I reported it in the review, erikhfj then pinned the deploy job to the intended runner. | | 2026-09-29 | erikhfj | opencode | Review fix for #27: `pull_request` no longer filters on `branches: [main]`, which had silently given stacked PRs zero CI runs | -| 2026-09-30 | rachelks | Codex (ChatGPT) | Assisted with reviewing the GraphQL schema in #35. I identified a missing paginated review connection required by the specification and requested changes; robertky corrected the schema before merge. | +| 2026-09-30 | rachelks | Codex (ChatGPT) | Assisted with reviewing the GraphQL schema in #35. I identified a missing paginated review connection required by the specification and requested changes; robertky corrected the schema before merge. | | 2026-09-30 | robertky | Codex (ChatGPT) | Helped me interpret Rachel's schema review on #35. | +| 2026-09-30 | evenkkl | Claude | Assisted with formulating reviews of PR #35, and identifying additional areas for improvement. | | 2026-10-01 | erikhfj | opencode | Answers to the open design questions: UUID as an `X-User-Id` header into the GraphQL context, narrowing facet counts, `id` tie-breakers, nulls last in both directions | -| 2026-10-01 | rachelks | Codex (ChatGPT) | Assisted with diagnosing the CI deploy failure after merge. The investigation traced the API restart issue to the `crate-api.service` check, `sudo` requiring a TTY, and a race while waiting for the API to start; erikhfj then fixed the deploy workflow. | +| 2026-10-01 | rachelks | Codex (ChatGPT) | Assisted with diagnosing the CI deploy failure after merge. The investigation traced the API restart issue to the `crate-api.service` check, `sudo` requiring a TTY, and a race while waiting for the API to start; erikhfj then fixed the deploy workflow. | | 2026-10-01 | erikhfj | opencode | CI deploy fix for #27 after rachelks reported it: `grep -q` SIGPIPE silently skipped a live service, `sudo` had no TTY, and `sleep 2` raced Node binding the port. All three verified against the live unit | | 2026-10-01 | erikhfj | opencode | Simplified this log to a table at the group's request | | 2026-10-01 | robertky | Codex (ChatGPT) | Assisted with formulating good reviews of the architecture and UI-specification PRs. The group decided to include decade filtering; Rachel implemented the corresponding schema and documentation update in #38. | -| 2026-09-28 | evenkkl | Claude | Assisted with formulating a schema for the Architecture decision in PR#36, and was a sparring partner to help understand why we should make the decisions we did. | -| 2026-09-30 | evenkkl | Claude | Assisted with formulating good reviews of PR#35, and find improvements one didnt catch on their own. + ## Notes - The prototype was never merged. `archive/scaffold-prototype` is a reference to