- Branch:
feature/requirement-comments, frommainat0c727ed. PR #30. - Scope: a comments area on the requirement page; any member, Observers and Reviewers included, adds comments and one level of replies without changing status, evidence, or decisions; author and time shown, oldest first; authors edit; authors, the Owner, and Admins delete; create/edit/delete recorded on the History page; email notifications for new comments and replies. User story: an Observer or Reviewer raises a question before sprint review (persona Angela, instructor). Recorded as ADR-059.
- Completed:
- API:
Requirements/CommentEndpoints.cs(GET/POST/requirements/{id}/comments, PATCH/DELETE/requirements/{id}/comments/{commentId}), writes under the team lock viaLockForMember;TeamRoles.CanManage;InputErrors.MaxCommentLength(5,000). - Migration
RequirementComments(tablesrequirement_comments,requirement_comment_events), generatorscripts/generate-requirement-comments.mjs(adds RLS) emittingdocs/schema/requirement-comments{,-rollback}.sql;scripts/test-database.mjsapplies it. - Web:
lib/comments.ts(parsing,threadComments,canEditComment,canDeleteComment,commentEventText,commentRecipients,commentNotificationEmail),listCommentsinlib/project-data.ts,formatDateTimeinlib/projects.ts, server actionsapp/projects/comment-actions.ts(add sends best-effort emails after saving),components/requirement-comments.tsx, a Comments section (#comments) on the requirement page, a Comments section on the History page, styles inapp-shell.css.
- API:
- Changed files: API
Requirements/CommentEndpoints.cs(new),Projects/ProjectAccess.cs,Data/{ProductModels,SpecThreadDbContext}.cs,Program.cs, migration + designer + snapshot;scripts/{generate-requirement-comments,test-database}.mjs,docs/schema/requirement-comments{,-rollback}.sql; web files above plus the requirement and history pages; tests newtests/{schema,api,e2e}/comments.spec.ts, migration counts bumped intests/schema/{evidence,github-repository,reviews}.spec.ts; docs DECISIONS (ADR-059), API, DATABASE, PROJECT, ARCHITECTURE, TESTING, this file. - Decisions and assumptions (user-chosen): email the thread (requirement author, all commenters, the parent's author for a reply; current members only; never the writer); author + Owner/Admin delete with a placeholder that keeps replies; events only, earlier text discarded. Own assumptions to confirm: Observers may also edit/delete their own comments; archived requirements make the discussion read-only; emails omit the comment text; deleted comments with no remaining replies are hidden from the page (still on History); times are shown in UTC. The stashed Kanban work needs ADR-060 or later.
- Checks (2026-11-18, local):
npm test431 passed (api, schema, chromium);npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes --no-restore,npm run build:api(0 warnings), andgit diff --checkpassed. Not exercised: real Resend delivery (tests useEMAIL_DELIVERY=log) and the shared Supabase database. - Known issues and risks: no in-app inbox, opt-out, or rate limit on notifications; a busy thread emails every participant on each comment. Rolling back the migration drops all comments. The shared database has not been migrated: apply TeamReviewerObserverRoles (if not already applied), then RequirementComments, then deploy the API.
- Unrelated work: Kanban WIP remains in
git stash("feature/kanban-board WIP (stashed before teams-and-roles)"). - Next step: team review of the assumptions above and PR #30; apply TeamReviewerObserverRoles, then RequirementComments, to the shared database before deploying the API.
- Branch:
feature/teams-and-roles, frommainat72a67bf. Merged tomainthrough PR #29 (0c727ed). - Scope: three user stories and one rule change, on one branch at the user's request. (1) Reviewer role: reads every project of the team and records decisions; cannot create, edit, or archive requirements or add or remove links; selectable when inviting. (2) Observer role: reads projects, requirements, and evidence; cannot edit anything or record decisions. (3) One combined projects view grouped by team; opening a team shows only its projects. (4) The creator of a requirement may approve or deny it (replaces ADR-038's second-person rule). Recorded as ADR-058.
- Completed:
- API:
TeamRolesinProjects/ProjectAccess.cs(CanEdit,CanReview,Assignable) andCallerRoleAsync.LockForMemberreturns the caller's role under the team lock. Every requirement, milestone, follow-up, evidence, suggestion, move, and document write answers 403EditorsOnlyfor Reviewers and Observers; GitHub-reading writes check before reading GitHub and again under the lock (Recheck.ReadOnly). Reviews: the author rule is gone; Observers get 403. Invitations and role changes accept all four roles; Admins invite and remove every role except Admin. - Migration
TeamReviewerObserverRoleswidens both role check constraints; generatorscripts/generate-team-reviewer-observer-roles.mjsadds a least-privilege rollback (removes Reviewer/Observer memberships and invitations) and emitsdocs/schema/team-reviewer-observer-roles{,-rollback}.sql;scripts/test-database.mjsapplies it. - Web: role types, parsers, labels, and
canManageTeam/canEdit/canReviewhelpers inlib/team-types.ts; everyrole !== "member"check (which would have given the new roles manager controls) now usescanManageTeam. Edit, archive, restore, new requirement, upload, milestone, follow-up, and evidence controls are hidden for Reviewers and Observers, with a read-only notice on the new/edit/upload pages; the review form is hidden for Observers; the author sees the form. Invite dialog offers Member/Reviewer/Observer (+Admin for the Owner) with a description of the chosen role; the members table offers all four roles./projectsgroups projects by team (groupProjectsByTeam) with the caller's role and an "Open team" link per team.
- API:
- Changed files: API
Projects/ProjectAccess.cs,Projects/ProjectEndpoints.cs,Requirements/{RequirementEndpoints,ReviewEndpoints,MilestoneEndpoints,FollowUpEndpoints}.cs,GitHub/{EvidenceEndpoints,EvidenceChangeEndpoints}.cs,Documents/DocumentEndpoints.cs,Teams/{InvitationEndpoints,TeamManagementEndpoints}.cs,Data/{SpecThreadDbContext,TeamModels}.cs, migration + snapshot; weblib/{team-types,projects,team-projects,invitation-types,invitations,email,project-data}.ts,components/review-panel.tsx,components/teams/{invitation-controls,team-members-table}.tsx,app/projects/page.tsx, project requirement/document pages, team settings/archive/members/ projects/invitations pages, invite preview,/projects/new,app-shell.css; tests newtests/schema/team-roles.spec.ts, updatedtests/schema/reviews.spec.ts,tests/e2e/{reviews,projects,project-failures,team-invitations,team-management}.spec.ts,tests/e2e/fixtures.ts,tests/api/project-data.spec.ts; docs DECISIONS (ADR-058, note on ADR-038), PROJECT, API, ARCHITECTURE, DATABASE, TESTING, this file. - Decisions and assumptions (confirm with the team): Reviewers and Observers can download documents and see project members (both are reads). Admins may invite Reviewers and Observers. Roles are per team, not per project. This is ADR-058; the stashed Kanban work also used an ADR number main has taken (057) and needs renumbering to 059 or later.
- Checks (2026-11-17, local):
npm test417 passed (api, schema, chromium);npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes --no-restore,npm run build:api(0 warnings), andgit diff --checkpassed. The new migration raised the hard-coded__EFMigrationsHistorycounts intests/schema/evidence.spec.ts,github-repository.spec.ts, andreviews.spec.tsby one. A stray test API left running on port 5116 since 2026-11-06 madeteams-api.spec.tsfail with 401/500 until it was stopped; if a schema spec fails on its first request, check for leftoverdotnet ... SpecThread.Api.dlllisteners on 51xx ports. Not exercised: the real GitHub and the shared Supabase database. - Known issues and risks: one person can now create and accept the same requirement, so "Accepted" no longer implies a second reviewer. Rolling back the migration removes Reviewer/Observer access. The shared database has not been migrated; apply TeamReviewerObserverRoles before deploying this API.
- Unrelated work: the uncommitted Kanban board work from
feature/kanban-boardis kept ingit stashas "feature/kanban-board WIP (stashed before teams-and-roles)"; restore it on that branch withgit stash pop. - Next step: team review of the ADR-058 assumptions above; commit, open a PR to
main, and apply the migration to the shared database before deploying.
- Branch:
feature/us-14-evidence-policy, frommainat031dd88, withmainmerged in atfd89908(PR #26 and #27). PR #28. - Scope: Jira SPEC-22 (US-14). The team's rule replaces ADR-053's, which was not a team decision (ADR-057). Acceptance criteria: the default policy requires a linked issue, a merged pull request, passing checks on its final commit, and a recorded release; a requirement missing any part shows which part; Evidence complete is shown separately from Accepted.
- Completed:
- API:
EvidencePolicy.Missingreturns the unmet parts in order (issue,merged_pull_request,passing_checks,release). The list and every single requirement response (get, create, update, archive, restore) carryevidenceCompleteandevidenceMissing. - Web: parsers read both fields (the previous API's list reads as no status, not the old claim); a row shows "Evidence complete" or "Missing issue, ..." (wrapping at phone width); the requirement page's Evidence section lists each part as Met or Missing under an "Evidence complete" or "Evidence incomplete" badge, apart from the Review section.
- API:
- Decisions and assumptions: an issue counts in any state. "A recorded release" means a linked release that GitHub confirmed contains the merged pull request (ADR-037), so an unrelated release does not satisfy it; with several merged pull requests, each needs passing checks and a release that contains it. Linked commits and unmerged pull requests neither count nor block. Without a merged pull request, checks and release are listed as missing too.
- Changed files: API
Requirements/EvidencePolicy.cs,Requirements/RequirementEndpoints.cs; weblib/projects.ts,lib/requirements.ts,components/requirement-rows.tsx, newcomponents/evidence-status.tsx, the requirement page,app-shell.css; teststests/schema/milestones.spec.ts(the rule test rewritten: 22 cases, list and single requirement, and the create, edit, archive, and restore responses),tests/e2e/milestones.spec.ts(row text, Met/Missing, the previous API, 390px),tests/api/project-data.spec.ts; docs DECISIONS (ADR-057, notes on ADR-038 and ADR-053), PROJECT, API, ARCHITECTURE, TESTING. No migration and no new environment variable. - Checks (on the PR's contents, after merging
mainatfd89908):npm test409 passed;npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes --no-restore,npm run build:api(0 warnings), andgit diff --checkpassed. Mutation check: each of 32 changed lines (17 API, 8 web parsing, 7 UI and layout) was broken one at a time and its tests run; three went uncaught at first (the edit response, an older API's malformed value, cut-off text on phones), tests were added, and all 32 now fail a test. Run locally with .NET SDK 10.0.114 (the only one installable in that environment;global.jsonpins 10.0.401 and was pointed at 10.0.100 only while checking, not committed). - Known issues and risks: requirements that were Evidence complete under the old rule (commits only, or no issue or release) stop being so after deploy, and list counts fall. A pull request merged after it was linked counts only once the evidence is refreshed. Not exercised: the real GitHub.
- Next step: review and merge PR #28; then move SPEC-22 to Done.
- Branch:
feature/pipeline-feedback, frommainat09848a9. - Scope: improve CI feedback, NuGet restore performance, and API deployment availability without changing application behavior, migrations, or production secrets.
- Completed:
.github/workflows/ci.ymlenables setup-dotnet NuGet caching keyed byapp/api/packages.lock.jsoninverifyanddeploy-api; restores remain locked.- Failed
verifyruns upload any available Playwright report and test results for seven days. - After a successful Render deploy-hook request,
deploy-apipolls the API's public/healthendpoint for up to five minutes (30 attempts, two-second request timeout, eight-second pauses) and fails clearly if it never returns the expected liveness response. docs/CI-PIPELINE-FEEDBACK.mdrecords the design and acceptance criteria; this guide records the CI behavior.
- Changed files:
.github/workflows/ci.yml,docs/CI-PIPELINE-FEEDBACK.md,docs/TESTING.md, and this handoff. - Validation: workflow YAML parsed and structural assertions passed; the health poll's
calculated worst case is 292 seconds. Passed
git diff --check,npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes --no-restore,npm run build,npm run build:api, andnpm test(409 passed). GitHub Actions has not run on this branch yet. - Risks and limitations:
/healthis liveness-only and may be answered by an already healthy instance; this does not prove the requested SHA is serving. Verifying the deployed revision would require Render deployment-status access or an API version endpoint. The health poll runs only after a merge tomain, not in a PR. - Next step: open a PR and confirm the workflow passes. After merge, check that the Render deployment reaches healthy status; compare CI restore duration after the NuGet cache has been populated.
- Branch:
feature/evidence-suggestions-and-moves, frommainat031dd88(PR #25 merged). - Scope: two stories for Danielle (Tech Lead), ADR-056: suggest links from explicit references such as "Closes #184" ("Design the Box" F2 / MVP scope), and move a wrongly linked pull request to the correct requirement ("Changing a requirement after its code was merged").
- User decisions: one branch; scan on request and on Refresh, not webhooks; a rejection stays rejected; any linked item can move, not only pull requests.
- Completed:
- Suggestions: pull requests of the connected repository whose description closes a
linked issue, read from the issue's GitHub timeline. "Find suggestions" and Refresh
update them. They are listed apart from the evidence, labeled "Suggested" with the
reference found, and count as nothing until confirmed. Confirm links the pull request
(
source = suggested); reject keeps it from coming back. Both are recorded with who and when, on the row and in the link history. - Moves: a Move control on each link, in one transaction, keeping the link's ID. Both requirements' link histories name the other. Decisions on both become outdated, release comparisons follow the link, and a pull request moved away isn't suggested back.
- Suggestions: pull requests of the connected repository whose description closes a
linked issue, read from the issue's GitHub timeline. "Find suggestions" and Refresh
update them. They are listed apart from the evidence, labeled "Suggested" with the
reference found, and count as nothing until confirmed. Confirm links the pull request
(
- Changed files: API
GitHub/EvidenceChangeEndpoints.cs(new),GitHub/EvidenceEndpoints.cs(SaveLinkAsyncsplit out of Link so confirming reuses it; history, refresh),GitHub/GitHubClient.cs(ListMentionsAsync),Data/ProductModels.cs,Data/SpecThreadDbContext.cs, migrationRequirementEvidenceSuggestionsand the snapshot;scripts/generate-requirement-evidence-suggestions.mjs, generateddocs/schema/requirement-evidence-suggestions*.sql,scripts/test-database.mjs,scripts/test-github.mjs(timeline); weblib/evidence.ts,lib/project-data.ts,app/projects/evidence-actions.ts,components/evidence-panel.tsx, the requirement page,app-shell.css; tests: newtests/schema/evidence-suggestions.spec.ts(5130, 5131), four tests intests/e2e/evidence.spec.ts, parser tests intests/api/project-data.spec.ts,tests/support/github.ts, migration counts up by one inreviews.spec.ts,evidence.spec.ts,github-repository.spec.ts; docs DECISIONS (ADR-056, ADR-036 note), API, DATABASE, ARCHITECTURE (nineteen product tables), PROJECT, TESTING. - Known issues and risks:
- Suggestions wait for someone to press Find suggestions or Refresh; there is no webhook.
- Only pull request descriptions are read, not commit messages or comments.
- Refresh makes one more GitHub call per linked issue and fails if that read fails.
- The real GitHub timeline format is not exercised by tests; try it once on a real repository before relying on it.
- The scaffold Suggestions page stays a placeholder; suggestions are on the requirement page.
- CI applies the migration on merge. Don't apply it to Supabase by hand first.
- Rolling the migration back deletes rejections, so rejected pull requests can be suggested again.
- Review follow-up (six comments, all valid): a scan or refresh saves nothing if the linked issues changed while GitHub was read; a truncated timeline drops no suggestions; a move needs a connected repository, rechecks under the lock that the link is still on the source and the target's links are unchanged, and leaves an earlier decision as it was.
- Checks:
npm test409 passed (it builds the web app and the Release API).npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes,has-pending-model-changes(none), andgit diff --checkpassed. - Next step: review, then open a PR to
main.
- Branch:
feature/observability, frommainatba2013f(PR #24 merged). - Scope: OpenTelemetry in the API and web app, exported to Grafana Cloud in deployment and
to an optional local viewer, off unless
OTEL_EXPORTER_OTLP_ENDPOINTis set (ADR-055, docs/OBSERVABILITY.md). Phase 2 (dashboards, alerts, Grafana Cloud setup) and Phase 3 (load testing) are separate PRs. - Completed:
- API:
Observability/ObservabilitySetup.cs, one call inProgram.cs. Traces (ASP.NET Core, HttpClient, Npgsql), metrics (hosting, Kestrel, HttpClient, runtime, Npgsql), logs (framework categories at Warning and above), OTLP/HTTP.url.pathreplaced by the route template;user.idfrom the JWTsub;/healthnot traced; an endpoint that is not an HTTP(S) URL stops startup. - Web:
src/instrumentation.tsandlib/telemetry.ts(@vercel/otelwith a redacting exporter: no raw paths or queries, URLs cut to scheme and host); trace context only to the API origin;client.addressfromx-real-ipon Vercel;user.idon the page-gate span inproxy.ts. - Tests: fake OTLP receiver (
scripts/test-otlp.mjs, 5126) started with the browser-test stack, so the browser suite runs with telemetry on;tests/api/telemetry.spec.ts(API on 5127/5128) andtests/e2e/telemetry.spec.tsguard tests; all test APIs blankOTEL_*. - Local viewer:
compose.observability.yaml(grafana/otel-lgtm:0.38.1, Grafana on 3030, OTLP on 4318, loopback only);npm run observability:up/observability:down. - Privacy page: a published "Operational telemetry" section (Grafana Labs, user ID, IP address, 14 days); the rest of the page stays a draft.
- API:
- Decisions (team, recorded in ADR-055): Grafana Cloud free tier for all signals; Jacob owns
the Grafana stack, the Vercel/Render owner sets the variables; user ID only (no team ID);
full client IP on web traces only; privacy page names Grafana Labs and IP addresses;
Preview deployments send nothing; Sentry deferred. Assumption: two variables suffice
(protocol, service names, and environment are set in code or by the platform). No
SpecThreadTelemetrysource/meter yet: there is no custom signal to put in it. - Changed files: API
Program.cs,SpecThread.Api.csprojandpackages.lock.json(OpenTelemetry 1.20.1 packages, Npgsql.OpenTelemetry 10.0.3), newObservability/; webpackage.json(@vercel/otel2.2.0,@opentelemetry/api1.9.1,@opentelemetry/sdk-trace-base2.12.0), newsrc/instrumentation.tsandsrc/lib/telemetry.ts,proxy.ts,privacy/page.tsx,components/policy-page.tsx,app-shell.css; rootpackage.json,package-lock.json,playwright.config.ts,compose.observability.yaml,render.yaml, both.env.example;scripts/test-otlp.mjs,scripts/start-test-web.mjs; testssupport/otlp.ts,support/api-process.ts,api/telemetry.spec.ts,e2e/telemetry.spec.ts,e2e/landing.spec.ts; docs new OBSERVABILITY, DECISIONS (ADR-055), DEPLOYMENT (Telemetry section), TESTING, ARCHITECTURE, AGENTS.md (one line on telemetry)..gitignoreignores*_plan.md. - Checks:
npm test395 passed (builds the web app and Release API);npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes --no-restore,git diff --checkpassed. The guard tests were seen to fail with redaction disabled on both sides. The API image built and booted as in theapi-imagejob (/healthok, anonymous/me401). Series budget: after the browser suite ran against the local viewer, the API had sent about 2,100 metric series (limit 10,000). With telemetry off the browser suite logs the same "destination stream closed early" errors from fault tests, so they are not caused by this change.npm auditreports critical/high advisories innext,better-auth,sharp,zod, andsource-map-jsthat predate this branch; none in the new packages. - Known issues and risks: not exercised are Vercel's
x-real-ip(read only on Vercel),@vercel/otelflushing before a Vercel function freezes, real Grafana Cloud, and the API sending nothing without an endpoint (nothing is registered; no receiver can observe it). IP addresses and user IDs sent to Grafana Labs are personal data. Grafana Cloud's Application Observability would add span-metric series against the same limit; leave it off. The PR touches shared files (Program.cs,playwright.config.ts,render.yaml, lockfiles): after it merges, teammates runnpm cianddotnet restore app/api. - Next step: review and open the PR to
main. After it merges and deploys, the Grafana owner and platform owner follow docs/DEPLOYMENT.md "Telemetry (ADR-055)" and verify.
- Branch:
feature/repository-connection-story, frommainat09848a9(PR #23 merged). - Scope: the story "connect one GitHub repository to a project" (Danielle, Tech Lead;
source "Design the Box" F2). All three criteria were already met by ADR-032 and
ADR-041; this task verifies them and closes the one test gap.
- Uses the SpecThread GitHub App: the repository is chosen from the installations the
user's GitHub token shows, and the API confirms the app can act there
(
app/api/GitHub/RepositoryEndpoints.cs). - Team Owner or Admin only:
CanManageTeam, checked again under the team lock; a Member gets 403, a non-member 404. - At most one repository:
project_repositoriesis keyed by project, so connecting again replaces it. The name shows in the project's Properties, in Settings, and on requirement pages.
- Uses the SpecThread GitHub App: the repository is chosen from the installations the
user's GitHub token shows, and the API confirms the app can act there
(
- Completed: an Admin who is not the Owner is now tested connecting and disconnecting, through the API and the browser (the Owner sees the name on the project, then "Not connected"). Test names that said "owner" for the Owner-or-Admin rule were corrected. The story is recorded in docs/PROJECT.md, and ADR-032 notes that ADR-041 replaced its owner-only rule.
- Changed files:
tests/schema/github-repository.spec.ts,tests/e2e/repository.spec.ts, docs PROJECT, DECISIONS (ADR-032 note), TESTING, HANDOFF. No product code or migration. - Checks:
npx playwright test tests/schema/github-repository.spec.ts(8 passed) andtests/e2e/repository.spec.ts(26 passed);npm run lint,npm run typecheck,git diff --checkpassed. - Known issues and risks: none new. As before (ADR-032), the repository name is a snapshot from connection time, and the real GitHub is not exercised by tests.
- Part 2, same branch at the user's request: the story "link GitHub issues and pull
requests to a requirement" (Danielle; "Design the Box" F2), ADR-054.
- Already met: linking by number or address (ADR-033); each link shows title, state
(open/closed/merged), and author;
linked_by/linked_atwere stored. - Completed:
- Find by title:
GET /requirements/{id}/evidence/search?q=asks GitHub's search API for issues and pull requests whose titles contain every word, at most 20, with state, author, and whether linked. Words are quoted, and results from another repository are dropped. A "Find by title" field lists results with Link buttons. - Every link now shows "Linked by on ".
requirement_evidence_eventsrecords each link added and removed (who, when, and the link's kind, label, and title), shown under the evidence and on the Requirement history page;GET /requirements/{id}/evidence/history.
- Find by title:
- Decisions (the user's): GitHub search over filtering recent items; record additions and removals, not removals only; stay on this branch.
- Changed files: API
GitHub/GitHubClient.cs(SearchItemsAsync),GitHub/EvidenceEndpoints.cs(search, history, events on link and unlink),Requirements/ReviewEndpoints.cs(sharedLabel),Data/ProductModels.cs,Data/SpecThreadDbContext.cs, migration20261030130820_RequirementEvidenceEventsand the snapshot;scripts/generate-requirement-evidence-events.mjs, generateddocs/schema/requirement-evidence-events*.sql,scripts/test-database.mjs,scripts/test-github.mjs(search); weblib/evidence.ts,lib/project-data.ts,app/projects/evidence-actions.ts,components/evidence-panel.tsx, the requirement and history pages,app-shell.css; tests: newtests/schema/evidence-history.spec.ts(5124, 5125), two tests intests/e2e/evidence.spec.ts, parser tests intests/api/project-data.spec.ts, migration counts up by one inreviews.spec.ts,evidence.spec.ts,github-repository.spec.ts; docs DECISIONS (ADR-054, ADR-036 note), API, DATABASE, ARCHITECTURE (eighteen product tables), PROJECT, TESTING. - Risks: search uses the repository name saved at connection, so after a rename it finds nothing until reconnected; GitHub search is rate limited (about 30 a minute per installation; shown as 502) and lags new items briefly; links changed by the previous API during the deploy are not recorded. CI applies the migration on merge.
- Checks:
npm test389 passed (it builds the web app and the Release API);npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes,has-pending-model-changes(none),git diff --checkpassed. The migration was applied to the local Docker database withdotnet ef database update. Not exercised: the real GitHub search API.
- Already met: linking by number or address (ADR-033); each link shows title, state
(open/closed/merged), and author;
- Next step: review, then open a PR to
maincarrying both stories and the migration.
Previous task: Criteria versions, accepted-criteria warning, follow-ups, and milestones (2026-10-29, merged as PR #23)
- Branch:
feature/requirement-change-tracking, frommainat8555d75(PR #22 merged). - Scope: four stories from the scenarios "Changing a requirement after its code was
merged", "Signing off a contract milestone", and "Checking student team progress":
- Danielle (Tech Lead): warn before editing the criteria of an Accepted requirement; confirming returns it to needing review with the earlier decision kept; cancelling changes nothing (ADR-051).
- Robert (Client Reviewer): every saved criteria change is a timestamped version, each decision shows its criteria version, and earlier versions open read-only (ADR-051).
- Danielle: mark a requirement as a follow-up of others in the project, shown on both with links, and adding and removing recorded with name and time (ADR-052).
- Danielle and Angela (Instructor): one milestone/sprint label per requirement, a list filter, and counts of Evidence complete and Accepted in the set (ADR-053).
- User decisions taken when planning: one branch for all four; a directional "follow-up of" link; a free-text milestone label; and a fixed built-in Evidence complete rule (no evidence policy existed).
- Completed:
- API:
requirement_criteria_versionsandrequirement_reviews.criteria_version; versions on create and on criteria changes only; catch-up versions for criteria the previous API saved during a deploy; 409accepted_criteria_changeunlessconfirmCriteriaChange;criteriaChanged/criteriaVersionon list review summaries; criteria-version GET endpoints; follow-up GET/POST/DELETE with an add/remove event log under the team lock;requirements.milestone,PUT /requirements/{id}/milestone(no version change),?milestone=on the list,GET /projects/{id}/milestones;evidenceCompletefromEvidencePolicy. - Web: the warning panel in the edit form ("Keep editing" sends nothing; "Save and request a new review" confirms; also opened by the API's 409); "Needs review" badge and notice; "Against criteria version N" on each decision; a read-only criteria version page; the Requirement history page (was a placeholder) listing versions with their decisions and the follow-up log; a Follow-ups section with add/remove and its log; a Milestone control on the requirement page and an optional field on the create form; the list's milestone filter, counts line, milestone chip, and Evidence complete badge. Parsers read fields missing from the previous API as empty (ADR-044).
- API:
- Changed files:
- API:
Requirements/RequirementEndpoints.cs,ReviewEndpoints.cs, newCriteriaVersionEndpoints.cs,FollowUpEndpoints.cs,MilestoneEndpoints.cs,EvidencePolicy.cs;Projects/ProjectAccess.cs(milestone validation);Data/ProductModels.cs,Data/SpecThreadDbContext.cs,Program.cs; migrations20261030001133_RequirementCriteriaVersions,20261030001226_RequirementMilestone,20261030001248_RequirementFollowUps,20261030013056_RequirementCriteriaVersionTexts(from review: version criteria must be an array of strings) and the snapshot. - Schema:
scripts/generate-requirement-criteria-versions.mjs,generate-requirement-milestone.mjs,generate-requirement-follow-ups.mjs,generate-requirement-criteria-version-texts.mjs(new), their generateddocs/schema/*.sqland*-rollback.sql,scripts/test-database.mjs. - Web:
lib/requirements.ts,lib/projects.ts,lib/reviews.ts,lib/project-data.ts, newlib/criteria-versions.tsandlib/follow-ups.ts;app/projects/requirement-actions.ts, newapp/projects/follow-up-actions.ts;components/requirement-form.tsx,requirement-rows.tsx,review-panel.tsx, newrequirement-follow-ups.tsxandrequirement-milestone.tsx; the requirement list, detail, new, edit, and history pages, newrequirements/[requirementId]/criteria/[version]/page.tsx;app-shell.css. - Tests: new
tests/schema/criteria-versions.spec.ts(5121),follow-ups.spec.ts(5122),milestones.spec.ts(5123); newtests/e2e/follow-ups.spec.tsandmilestones.spec.ts; two warning tests intests/e2e/reviews.spec.ts; parser and helper tests intests/api/project-data.spec.ts; the review summary shape intests/schema/reviews.spec.ts; migration-history counts up by four inreviews.spec.ts,evidence.spec.ts, andgithub-repository.spec.ts; the history page listed as connected intests/e2e/scaffold.spec.ts. - Docs: DECISIONS (ADR-051, 052, 053; notes on ADR-024, 038, 050), API, DATABASE, ARCHITECTURE (seventeen product tables), PROJECT (Evidence complete), TESTING.
- API:
- Decisions and assumptions:
- "Needs review" is derived, like "outdated": no decision row is written when accepted criteria change, so the acceptance stays in the history as made.
- Criteria compare as ordered, trimmed texts, so reordering is a new version and needs a new review. Title, description, and document edits are not criteria versions.
- The warning applies only while the latest decision is an acceptance on the current criteria version; after a newer rejection, criteria change without it.
- Setting a milestone and linking follow-ups are not edits: no version change, so no decision becomes outdated.
- Accepted in the counts means a latest acceptance that is neither outdated nor on earlier criteria.
- Checks (all run on this branch, 2026-10-29):
- Passed:
npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes --no-restore,dotnet ef migrations has-pending-model-changes(none),npm run build,npm run build:api(0 errors),git diff --check. npm test: 380 passed, none flaky or failed.- Not run: applying the three migrations with the EF bundle to a Postgres at the RequirementUpdatedBy state, as CI will. The generated SQL scripts were applied by the schema tests, including the backfill and each rollback.
- Passed:
- Known issues and risks:
- CI applies the four migrations on merge, in order (ADR-044). Don't apply them to Supabase by hand first.
- Criteria saved or decisions recorded by the previous API during the deploy have no version until the next save or decision (catch-up), and such a decision shows "Criteria version not recorded", as do decisions made before versioning on an older requirement version.
- Milestone labels match exactly; there is no milestone record, rename, or date, and the Milestones page is still a placeholder.
- Evidence complete is a fixed rule using check results from the last GitHub refresh.
- Playwright prints a pg "terminating connection due to administrator command" stack
from the shared web test database when the run ends; it happens on
maintoo and does not fail tests.
- Outcome: merged to
mainas PR #23 (09848a9). A local Docker database for manual testing (specthread-local-db, port 54329) has every migration applied withdotnet ef database update. Possible follow-ups: a Milestones page built on the labels, an edit history for titles and descriptions, and a configurable evidence policy.
Previous task: Requirement criteria rule, creation date, linked documents, last editor, and restore (2026-10-23, merged as PR #22)
- Branch:
feature/requirements-documents, frommainatb069093. - Scope: the "create a requirement" story (Danielle, Tech Lead; source "Design the Box" F1, recorded in docs/PROJECT.md), plus linking project documents from requirements (ADR-049). Two of the story's four criteria were already met: each criterion is its own row and list item, and only team members can create (404 otherwise).
- Completed:
- A requirement can't be created or saved without at least one acceptance criterion
(API 400 on
acceptanceCriteria, same message in the form). The form starts with one empty criterion row. - The requirement page shows "Created by on " as well as the update date.
- Requirements link up to 20 documents from their own project, ticked in the requirement form and saved with the requirement (the version rises). Kept links keep who linked them and when. Archived documents can't be newly linked; ones linked before archiving stay, marked Archived, until unticked. The page lists linked documents, each opening its document page.
- A requirement can't be created or saved without at least one acceptance criterion
(API 400 on
- Changed files:
- API:
Requirements/RequirementEndpoints.cs,Projects/ProjectAccess.cs(minimum criterion, document limit),Data/ProductModels.cs,Data/SpecThreadDbContext.cs, migration20261024003629_RequirementDocumentsand the model snapshot. - Schema:
scripts/generate-requirement-documents.mjs(new), generateddocs/schema/requirement-documents.sqland-rollback.sql,scripts/test-database.mjs. - Web:
lib/requirements.ts(types, parsing, validation,documentChoices),components/requirement-form.tsx,app/projects/requirement-actions.ts, the new, edit, and detail requirement pages,app-shell.css. - Tests: new
tests/schema/requirement-documents.spec.ts(API on 5120); zero-criteria andcreatedAtchecks intests/schema/product-api.spec.ts; requirement and document e2e tests intests/e2e/requirements.spec.ts; unit tests intests/api/project-data.spec.ts. Existing tests now send or fill one criterion (schema: product-api, reviews, evidence, team-management; e2e: requirements, reviews, evidence), and migration-history counts rose by one. - Docs: DECISIONS (ADR-049, and an ADR-047 cross-reference), API, DATABASE, ARCHITECTURE (fourteen product tables), PROJECT (the story), TESTING.
- API:
- Decisions and assumptions:
- Links are saved with the requirement rather than through separate link endpoints, so a link change is a new version and makes an earlier review outdated.
- The criterion minimum is an API rule, not a database constraint. Existing requirements with no criteria stay readable but need one before their next save.
- Document checkboxes take their default from React state, so ticks survive the form reset after a server-side rejection (a controlled checkbox did not).
- Checks (all run on this branch):
- Passed:
npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes,dotnet ef migrations has-pending-model-changes(none),git diff --check. npm test: 356 passed, none flaky.- CI's migration path: the EF bundle applied only RequirementDocuments to a Postgres 17 at the ProjectDocuments state (RLS on, anon has no SELECT, 14 history rows), and a second run applied nothing.
- Passed:
- Known issues and risks:
- CI applies RequirementDocuments on merge (ADR-044). Don't apply it to Supabase by hand first; a draft applied early broke the ProjectDocuments deploy.
- A document's page doesn't list the requirements that link it yet.
- The uncommitted
app/api/packages.lock.jsonchange that was onmainbefore this branch was overwritten bydotnetrestores during the work; the file now matches the committed version.
- Part 2, same branch at the user's request (ADR-050): the story criteria "edits save the
editor's name and a timestamp", "archived requirements are hidden from the default list
but can still be opened read-only", and "archived requirements can't be edited or
reviewed until restored".
- Completed:
requirements.updated_byrecords who saved the current version; the page reads "Updated by on ". The Requirements tab links to an Archived view (?archived=true, APIarchived=true).POST /requirements/{id}/restore(any team member, refused in an archived project) restores without raising the version or changing the last editor; the archived page offers Restore, and its edit page links to it. Archived requirements still refuse saves, evidence changes, and reviews (409). - Decision: last editor only, not an edit history (the user's choice). The column is nullable so the API still running during the deploy can create requirements; the migration backfills the creator and the API reports the creator for an empty value.
- Changed files:
RequirementEndpoints.cs(list filter, restore,UpdatedBy),ProductModels.cs,SpecThreadDbContext.cs, migration20261024010934_RequirementUpdatedByand the snapshot,scripts/generate-requirement-updated-by.mjswith generateddocs/schema/requirement-updated-by.sqland-rollback.sql,scripts/test-database.mjs; weblib/project-data.ts,lib/requirements.ts,requirement-actions.ts,components/requirement-archive.tsx(addsRequirementRestore),components/requirement-rows.tsx, the requirement list, detail, and edit pages; tests intests/schema/product-api.spec.ts,reviews.spec.ts, history counts inevidence.spec.tsandgithub-repository.spec.ts,tests/api/project-data.spec.ts, andtests/e2e/requirements.spec.ts; docs DECISIONS (ADR-050, ADR-024 note), API, DATABASE, ARCHITECTURE, PROJECT, TESTING. - Checks: lint, typecheck,
dotnet format --verify-no-changes,has-pending-model-changes(none),git diff --checkpassed;npm test359 passed, none flaky. The EF bundle applied RequirementDocuments then RequirementUpdatedBy to a Postgres at the ProjectDocuments state with one existing requirement, whoseupdated_bybecame its creator. - Risks: who made earlier edits isn't recorded. Any team member can now undo an archive.
- Completed:
- Outcome: merged to
mainas PR #22 (8555d75). Remaining follow-ups: show linking requirements on a document's page, and Tickets. The edit history is partly covered by criteria versions (ADR-051).
- Branch:
fix/evidence-locks-and-timeouts, frommainatdac2bcd. Fixes only; no new features and no schema change. - Problems (from a full scan of
main, where every check passed):- Refreshing evidence failed in the browser once it took longer than
apiFetch's 10-second limit, which a requirement with about 20 or more linked pull requests reaches. - A refresh that met a concurrent unlink answered an unhandled 500.
- Evidence link/refresh/unlink, review decisions, and repository connect/disconnect did not take the team lock, so they could commit into a project being archived or for a member being removed. Two links at once could pass the 50-link limit.
docs/API.mdanddocs/ARCHITECTURE.mddisagreed with the code.
- Refreshing evidence failed in the browser once it took longer than
- Completed (ADR-048):
- Those six writes run in a transaction that locks the project's team and re-reads
membership and archived state (
RequirementEndpoints.LockForMember, now internal, orProjectEndpoints.LockProjectForCaller). Link, refresh, and connect read GitHub first, without the lock, then lock, check again (member, not archived, same repository), and save. Link counts links again under the lock. A row removed while GitHub was read answers 409 "The evidence changed while it was being read from GitHub. Reload and try again." apiFetchtakes an optionaltimeoutMs; link and refresh use 55 seconds, and the requirement page setsmaxDuration = 60. Every other call keeps 10 seconds and the GET retry.- Docs: repository connect/disconnect is team Owner/Admin; the retired add-member paragraph, a stray code fence that turned the rest of API.md into code, and two stale ownership notes are removed; ARCHITECTURE no longer calls the GitHub App pending.
- Those six writes run in a transaction that locks the project's team and re-reads
membership and archived state (
- Changed files:
- API:
GitHub/EvidenceEndpoints.cs,GitHub/RepositoryEndpoints.cs,Requirements/RequirementEndpoints.cs,Requirements/ReviewEndpoints.cs. - Web:
lib/api.ts,app/projects/evidence-actions.ts,app/projects/[projectId]/requirements/[requirementId]/page.tsx. - Tests: new
tests/support/team-lock.ts(holds a team's row lock from the test database); new cases intests/schema/{evidence,reviews,github-repository}.spec.tsandtests/e2e/evidence.spec.ts. - Docs:
API.md,ARCHITECTURE.md,DECISIONS.md(ADR-048), this file.
- API:
- Decisions and assumptions: GitHub is never read while the team lock is held, so a slow GitHub cannot stall the team's other writes. A refresh that loses a race is refused rather than merged. 55 seconds leaves the server action time to answer before Vercel's 60.
- Checks:
- The six new tests failed against the old code: the lock tests completed without waiting, and the browser refresh hit the 10-second timeout. All six pass with the fix.
- Passed:
npm run lint,npm run typecheck,npm run build:api,dotnet format app/api --verify-no-changes --no-restore,dotnet ef migrations has-pending-model-changes(no changes), andgit diff --check. CI=1 npm test: 347 passed (341 before, plus the six new tests). Run with Chromium 141 instead of the version Playwright 1.63 expects.
- Known issues and risks:
- The first refresh of a requirement with many releases and many merged pull requests can still approach 55 seconds (one GitHub compare per release and change pair).
maxDuration = 60is not verified on Vercel from here.- Still out of scope from the scan: the Playwright verification feature, audit history, evidence policies, suggested links and webhooks, the sample dashboard, and the placeholder pages.
- Next step: review and merge the pull request, then refresh a requirement with many links on spec-thread.com and confirm it completes.
- Branch:
feature/project-docs, rebuilt onorigin/mainat35b407c. The first version was written before the teams, tabs, and black-and-white work reachedmain; it is kept locally asbackup/project-docs-v1and was ported, not merged. The pre-existing uncommitted deletion ofapp/api/.env.exampleis unrelated and was left untouched. - Completed (ADR-047):
- The API lets any member of a project's team upload PDF, DOC, and DOCX files of up to 4 MiB, list them newest first, download them, and archive them. Writes lock the team like other project writes.
- The API checks each file's leading bytes against its extension. Non-members get 404. Archived projects refuse uploads and archiving with 409.
- Web: a Documentation project tab, between Requirements and Settings. It has a list (empty state; no upload button on archived projects) and an upload page that checks files in the browser and shows the server's messages.
- A page per document shows its details, a Download link, and archive with confirmation. A route serves downloads (read in full, so a failed transfer is a 502) and answers 404 when the address names another project.
- The user asked for a project "sub menu"; on
mainproject sections are tabs (ADR-028), so it is a tab. - Tickets (bug, issue or task, and user story, with states) were also requested. They are deferred to a separate task.
- Changed files:
- API:
app/api/Documents/DocumentEndpoints.cs(new),Data/ProductModels.cs,Data/SpecThreadDbContext.cs,Program.cs, migration*_ProjectDocuments*, and the model snapshot. - Schema:
scripts/generate-project-documents.mjs(new), generateddocs/schema/project-documents.sqlandproject-documents-rollback.sql,scripts/test-database.mjs. - Web, new:
lib/documents.ts,app/projects/document-actions.ts,components/document-upload-form.tsx,components/document-archive.tsx, andapp/projects/[projectId]/documents/**. - Web, changed:
lib/project-data.ts(listDocuments,requireDocument),lib/api.ts(JSON content type only for string bodies),components/project-tabs.tsx,app-shell.css, andnext.config.ts(server action body limit 5 MB). - Tests:
tests/schema/documents-api.spec.ts,tests/api/document-files.spec.ts,tests/e2e/documents.spec.ts(new), andtests/api/products.spec.ts. - Tests, adjusted:
tests/e2e/projects.spec.ts(tab list); the migration-history counts intests/schema/evidence.spec.ts,github-repository.spec.ts, andreviews.spec.ts, each one higher;scripts/test-api-proxy.mjs, which now forwardsContent-Disposition. - Docs: DECISIONS (ADR-047), API, DATABASE, ARCHITECTURE, PROJECT (MVP scope), TESTING. DATABASE and ARCHITECTURE said "eight product tables"; the model has thirteen with this change (eleven before it), so both now say thirteen.
- API:
- Decisions and assumptions:
- Files are stored as bytea in PostgreSQL (the user's choice). The 4 MiB limit follows from Vercel's 4.5 MB function body limit.
- Access follows team membership like requirements, so any team Member may archive.
- Documents are archived, never deleted. There is no unarchive yet.
- Checks:
- Passed:
dotnet format app/api --verify-no-changes,npm run lint,npm run typecheck,dotnet ef migrations has-pending-model-changes(none), andgit diff --check. npm test: 341 passed on the last two full runs.- The first full run after the port also failed
documents-api"uploads are checked…" andauth-jwt-runtimeonce each. Their errors were not captured, and neither recurred in two full runs or in 15 repeats of the documents spec in one worker.
- Passed:
- Known issues and risks:
- CI applies ProjectDocuments on merge (ADR-044); rollback deletes every uploaded file.
- Files use database space (500 MB on the free plan), and archiving frees none.
- There is no virus scanning, and DOC/DOCX contents past the header are not inspected.
- After a server-side rejection the file input is cleared (React's form reset); the title is kept.
- Next step: review and merge the PR. Follow-ups are citing documents from requirements, and Tickets.
- Branch:
fix/onboarding-gate-failure(PR #19, at the user's request, together with the gate fix below). - Causes found: the web app ran in Vercel's
iad1while Supabase and the API are in Oregon; every Vercel instance and preview shared the session pooler's 15 connections;apiFetchhad no timeout or retry; an idle connection dropped by the database crashed the process through pg's unhandled "error" event; the sidebar replaced its team list with an error whenever a refresh failed. - Completed (ADR-046):
app/web/vercel.jsonregionpdx1;apiFetchtimeout and one retry for GETs (never writes) and for the token exchange; poolidleTimeoutMillisand a pool "error" handler; sidebar keeps its list on a failed refresh and retries a failed first load. The sidebar still refreshes on navigation, because creating, joining, and leaving a team redirect server-side without the change event. - Changed files:
app/web/{vercel.json,src/lib/api.ts,src/lib/auth-config.ts,src/lib/create-auth.ts},app/web/src/components/teams/team-sidebar-links.tsx,tests/e2e/{project-failures,teams}.spec.ts,docs/{DATABASE,DEPLOYMENT,DECISIONS,HANDOFF}.md. - Your action: in Vercel (Production and Preview) set
DATABASE_URLto the transaction pooler, port 6543 with?sslmode=require; then confirm the Functions region showspdx1. - Checks:
npm run lint,npm run typecheck,git diff --check: passed. One fullCI=1 npm testrun: 329 passed, with nouncaughtExceptionin the server log (a dropped idle connection had produced one before the pool "error" handler). New tests: one-time 500/503/dropped-connection reads are retried and the page shows data; a failed write is not retried; a brief/api/teamsfailure recovers; a failed refresh keeps the shown teams. - Exact next step: merge PR #19, change
DATABASE_URL, and compare Vercel request durations and error logs before and after.
- Branch:
fix/onboarding-gate-failure, frommainat5173f56. - Problem: on spec-thread.com, a signed-in user's landing Dashboard link did nothing and
team pages showed a plain "Internal Server Error". The page gate (
app/web/src/proxy.ts) threw whenever itsGET /onboardingcall to the API failed, before the setup cookie (ADR-042) existed, so every signed-in navigation failed. - Completed: the gate now logs the failure (with the status, and a hint that 401 means
Auth__Issuerdiffers fromBETTER_AUTH_URL) and lets the page render without the cookie. The session check still fails closed. Recorded as ADR-045. DEPLOYMENT.md examples now usehttps://spec-thread.comas the issuer, and its troubleshooting covers the log line. - Changed files:
app/web/src/proxy.ts,tests/e2e/onboarding.spec.ts,docs/{DECISIONS,DEPLOYMENT,HANDOFF}.md. - Assumption: the live failure is most likely Render's
Auth__Issuerstill naming the old vercel.app origin after the move to spec-thread.com. Not verified: Vercel and Render settings and logs were not reachable from this environment. - Checks:
CI= npx playwright test --project=chromium tests/e2e/onboarding.spec.ts -g "setup check fails": failed against the old gate (the dashboard never loaded; the server logged "Account setup could not be checked."), passes with the fix.- Onboarding, landing, protection, shell, and teams browser specs: 39 passed. Without the new test, no "Onboarding check failed" line is logged.
npm run lint,npm run typecheck,git diff --check: passed.CI=1 npm test, one full run: 324 passed.
- Exact next step: merge, then confirm Render
Auth__Issuerequals VercelBETTER_AUTH_URL(https://spec-thread.com) and that Vercel logs show no "Onboarding check failed" line.
- Branch:
feature/ci-db-migrations, frommainat3d8d68e, withmainmerged in at3868cef(PR #17, page load time). One pull request intomain. - Completed (ADR-044):
.github/workflows/ci.yml: new jobdeploy-api, on pushes tomainonly, afterverifyandapi-image. It builds an EF migration bundle, trusts the Supabase CA, applies pending migrations, then calls Render's deploy hook withrefset to the commit. It runs in the GitHub environmentapi-deploy, one at a time, never cancelled midway.render.yaml:autoDeployTrigger: off.docs/{DECISIONS,DATABASE,DEPLOYMENT,TESTING,HANDOFF}.md.
- Decisions and assumptions:
- The environment is
api-deploy, notproduction: GitHub environment names ignore case, and Vercel already uses Production. Render'smain - specthread-apiis left to Render. - Muhammad reports
api-deployis configured withDATABASE_MIGRATION_CONNECTION_STRINGandRENDER_DEPLOY_HOOK_URL, and Render's auto-deploy is handled. Not checked here. - Building the bundle needs a connection string; a dummy is used. Checked locally: the
bundle reads
ConnectionStrings__Databasewhen it runs (an unreachable host was tried, not the dummy), and exits 1 when none is set.
- The environment is
- Checks: listed in the pull request; the job itself runs only after the merge.
- Known issues or risks:
- Merging this pull request runs the job for the first time, against Supabase. If a
migration was ever applied without its
__EFMigrationsHistoryrow, that run fails on it. - The bundle was never run against a real database here (Docker was not running). The deploy hook call and the CA install were not run outside CI.
- Each migration must work with the API already running (ADR-044). Rollback is manual.
- Merging this pull request runs the job for the first time, against Supabase. If a
migration was ever applied without its
- Next step: run
dotnet ef migrations list --project app/apiagainst Supabase (read only) and confirm no migration shows as pending that is already in the database; then merge, and approve thedeploy-apirun ifapi-deployrequires a reviewer.
- Branch:
fix/page-load-time, rebuilt onmainat3d8d68e(PR #16 merged). Merged intomainas PR #17. - Problem: every page took about two seconds against the hosted database, and the dev server's log showed Supabase refusing connections ("max clients reached in session mode ... pool_size: 15").
- Completed (ADR-043):
app/web/src/lib/create-auth.ts: the jwt plugin no longer signs a token on every session read (disableSettingJwtHeader).app/web/src/lib/auth.ts: one auth instance, and so one database pool, per process.app/web/src/lib/auth-config.ts: the web pool holds at most 4 connections.app/api/Program.cs: the API pool holds at most 5 unless the connection string setsMaximum Pool Size.docs/DATABASE.mdexplains the shared 15-connection limit.
- Merged with PR #16, which did overlapping work (ADR-042). Kept
main's version where both sides did the same thing: the signed onboarding cookie instead of this branch's one-hour in-memory cache, Reactcache()for the per-render token instead of this branch's 60-second token cache, and per-test client IPs instead of clearing therateLimittable intests/e2e/home.spec.ts. The project page parallel reads were already identical. Soapp/web/src/lib/request-cache.tsandtests/api/request-cache.spec.tsare not in this branch; the earlier version is ingit stash("fix/page-load-time local work before merging main") on Muhammad's machine. - Checks on the merged code:
npm run lint,npm run typecheck,npm run build:api,dotnet format app/api --verify-no-changes --no-restore, andnpm run buildpassed. Tests were not run locally (they run in CI); no test changed in this branch. - Known issues and risks:
- Not measured against the hosted database, and the earlier statement counts (dashboard 170 to 27, requirement page 300 to 69) were taken with the replaced caches, so they have not been measured for this combination.
- The 15-connection limit is shared by local development, Vercel, and Render when they use the same session pooler. The caps make exhaustion unlikely, not impossible; the transaction pooler (port 6543) is the lasting fix and is not set up or tested.
- About one session read per prefetched link remains. Reducing it needs a decision: let the gate trust a recent session check (sign-out would take that long to apply), or prefetch fewer links.
- Next step: try the app against the hosted database and decide on the remaining session reads.
- Branch:
fix/stabilize-current-features, frommainatc1928d9. Fixes only; no new features. Opened as one pull request intomain. - Completed:
- CI on
mainwas red: the home page tests got 429 from Better Auth's rate limit, because every browser test came from 127.0.0.1. Each test now has its own client IP (tests/e2e/fixtures.ts). The rootpackage.jsonnow pins better-auth 1.7.5, as the web app does, so the lockfile resolves one copy. - Fewer repeated lookups on the web side (ADR-042). The page gate remembers finished
setup in a signed cookie instead of calling the API on every navigation;
apiFetchexchanges the session for a token once per render; team pages look up the session once; project, requirement, and team pages start their API reads together. - API fixes. Requirement create, update, and archive lock the project's team, so nothing is written to a project that is being archived. A GitHub secondary rate limit (403 with retry-after) is reported as GitHub unavailable (502); before, refresh quietly kept stale data.
- Evidence refresh reads GitHub with up to four calls at once and keeps earlier "included" answers while the release and change commits are unchanged.
- Sign-in pages show only the providers this deployment has configured. Login treats only EMAIL_NOT_VERIFIED as "verify your email", and reset treats only INVALID_TOKEN as an expired link.
- When a requirement's author is the only member of the team, the review notice links to the team's invitations. The review rule (ADR-038) is unchanged.
- Baseline security headers (no framing, nosniff, referrer policy); CI actions on v5.
- A new CI job,
api-image, builds and boots the Docker image Render deploys and checks/health, Production behavior, the non-root user, and the Supabase CA. Before this, no check covered the API deployment.
- CI on
- Changed files:
app/web/src/{proxy.ts,lib/{api,teams,team-projects,invitations,sign-in-methods,onboarding-cookie,create-auth}.ts}, project/team/login/signup/account pages,components/{auth-form,password-forms,review-panel}.tsx,app/web/next.config.ts,app/api/{Requirements/RequirementEndpoints,Projects/ProjectEndpoints,GitHub/EvidenceEndpoints,GitHub/GitHubClient}.cs,scripts/test-github.mjs,playwright.config.ts, tests intests/{e2e,api,schema,support},.github/workflows/ci.yml,package.json,package-lock.json, anddocs/{ARCHITECTURE,DECISIONS,TESTING,HANDOFF}.md. - Decisions and assumptions:
- ADR-042 (setup cookie and per-render reads).
- Kept as is, on purpose: a half-configured Google sign-in still disables Google rather
than failing startup (ADR-016 and its test);
enforce-pr.ymlis unchanged. - The deleted-release case in the release evidence test now uses a commit history that real git can produce, because reused "included" answers assume history for a fixed SHA does not change.
- Checks, all on the final code:
npm run lint,npm run typecheck,dotnet format app/api --verify-no-changes --no-restore,npm run build:api,npm run build,dotnet ef migrations has-pending-model-changes(no changes; run with a dummy connection string),git diff --check, and one fullCI=1 npm test: 323 passed. Before the changes, the same full run had 316 passed and 1 failed with the 429. The new secondary rate-limit test failed against the old client code. The revoked-session test passed 15 repeated runs after its missingawaitwas fixed. - Known issues or risks: none of these were run against Vercel, Render, or Supabase.
Chromium 141 was used locally instead of the version Playwright 1.63 expects. The CI
action upgrade is verified only by the pull request's own CI run.
mainhas no branch protection; protecting it and requiring theverifycheck is a repository setting a maintainer must change. Out of scope (new features): webhooks, an audit trail, the Playwright verification feature, real dashboard data, the placeholder pages, and privacy/terms content. - The
api-imagesteps were run locally against the image's real runtime stage: all passed, and the CA check failed for an image built without the CA. The local build had to trust this sandbox's HTTPS proxy in a scratch copy of the build stage; the repository's Dockerfile is unchanged. - Exact next step: review and merge the pull request after its CI is green, then protect
mainin the repository settings and require bothverifyandapi-image.
- Branch:
feature/project-ui, mergingorigin/mainat0e6077b(PR #14, teams). The merge is resolved in the working tree and not committed;git commitcompletes it. PR intomainafterwards. - Completed (ADR-041):
- The 14 conflicted files are resolved. The EF model snapshot was stitched from both sides and EF reports no pending model changes.
- Things Git did not flag but the merge broke: repository connect and disconnect
called a permission helper main removed (now the team's Owner or an Admin, as
for renaming a project); creating a project needs a team (the form has a Team
field, offers only teams the user owns or administers, and
/projects/new?team=<id>preselects one; the team's project list links to it); project pages decide what to show fromteamRole; both branches had added a browser-test API on port 5106 (one kept, with main's readiness wait); the teams API tests used ports 5107 to 5109, which this branch's test proxy and GitHub stand-ins already use (moved to 5116 to 5118). - main's decisions ADR-026 and ADR-027 are renumbered ADR-039 and ADR-040, because this branch had used those numbers. References in main's code, tests, and docs follow.
- This branch's tests create a team before a project and add people to the team
instead of to the project (
createTestTeam,addTestTeamMemberin tests/e2e/fixtures.ts).
- Changed beyond the conflicted files:
app/api/GitHub/RepositoryEndpoints.cs,app/web/src/lib/projects.ts,app/web/src/app/projects/{actions,repository-actions}.ts,app/web/src/app/projects/{page,new/page}.tsx,app/web/src/app/projects/[projectId]/{page,settings/page,settings/repository/page}.tsx,app/web/src/components/project-form.tsx,app/web/src/app/app-shell.css,app/web/src/app/teams/[teamId]/projects/page.tsx(New project link), the six project, requirement, repository, evidence, and review browser specs,tests/schema/{evidence,reviews,github-repository}.spec.ts,tests/api/project-data.spec.ts, and the ADR references noted above. - Checks, all after the last code change: every schema-project spec passed (76),
including both branches' API and migration tests run together; every browser test
plus the parser tests passed (207).
dotnet build app/api --configuration Release,dotnet format app/api --verify-no-changes --no-restore,npm run lint, andnpm run typecheckpassed.dotnet ef migrations has-pending-model-changesreported none. Run with a temporary config because the dev API held port 5100, so the api-project tests that need that port (health, JWT, OpenAPI) were not run. - Known issues and risks:
- Setup:
dotnet ef database update --project app/apiwith the API stopped applies whichever migrations the database lacks (docs/DATABASE.md, "Combined migration order"). TeamProjects turns each existing project into its own team. - Team pages use their own styles (teams.module.css) and are not yet in the black-and-white system. Not changed here.
- Not verified against the live database or the real GitHub.
- Setup:
- Next step: commit the merge, push, and let the PR's checks run. Then the AI slice under ADR-036.
- Branch:
feature/project-ui. Uncommitted, together with the reorder entry below unless that has been committed since. - Completed: each row on the Requirements tab and the overview's recent requirements
says "No evidence", "1 evidence link", or "N evidence links", before the review
badge.
GET /projects/{projectId}/requirementsreturnsevidenceCountper requirement, counted from the evidence IDs that endpoint already loaded. No database or migration change. - Changed files:
app/api/Requirements/RequirementEndpoints.cs,app/web/src/lib/{projects,requirements,evidence}.ts,app/web/src/components/requirement-rows.tsx,app/web/src/app/app-shell.css,tests/schema/reviews.spec.ts,tests/e2e/{evidence,reviews}.spec.ts,tests/api/project-data.spec.ts,docs/{API,TESTING}.md, and this file. No ADR. - Differences from the plan:
reviewedTextinlib/reviews.tskeeps its own wording ("with no evidence links") instead of sharing the new helper, because the two sentences read differently at zero. - Checks: after the last code change, all browser tests plus
tests/schema/{evidence,github-repository}.spec.tspassed (191), including the session test that failed under load in the previous entry. Before that,tests/schema/reviews.spec.ts,tests/api/project-data.spec.ts, and the evidence and review browser tests passed together (47).npm run lint,npm run typecheck, the Release API build, anddotnet format app/api --verify-no-changes --no-restorepassed. Run with a temporary config because the dev API held port 5100; the api-project tests on that port and the older schema specs were not rerun. - Known issues and risks:
- Setup: restart or redeploy the API with this build. The web now requires
evidenceCount; against an older API the requirement lists show the error page. - The count says how much is linked, not whether it is enough or passing.
- Setup: restart or redeploy the API with this build. The web now requires
- Next step: the AI slice under ADR-036 (suggestions only; a person decides). It needs a plan and decisions first: provider, what is sent to it, and where suggestions appear.
- Branch:
feature/project-ui. Review decisions are committed (643f36a). This entry is uncommitted. The approved plan is in~/.claude/plans/yes-i-want-to-delightful-sunset.md. - Completed: on the create and edit requirement forms each criterion has "Move criterion N up" and "Move criterion N down" buttons. The order on screen is the order saved. Web only: the API already stores criteria in the order sent, so there is no API, database, or migration change and nothing to set up.
- Changed files:
app/web/src/components/requirement-form.tsx,app/web/src/lib/requirements.ts(moveItem),app/web/src/app/app-shell.css,tests/e2e/requirements.spec.ts,tests/api/project-data.spec.ts,docs/TESTING.md, and this file. No ADR: no product rule or boundary changed. - Decisions and differences from the plan:
- A button that cannot move its row is
aria-disabled, notdisabled, and does nothing when pressed. That keeps keyboard focus on it when a row reaches the top or bottom, so no focus is moved by code (the plan had focus jump to the other button). - A message about one criterion is now shown on the row that was sent at that position, so it follows the row when rows are moved or removed. Before, it stayed at the position and could sit beside the wrong row after a removal.
- A hidden
role="status"line says where a moved criterion now is.
- A button that cannot move its row is
- Checks:
tests/e2e/requirements.spec.tsandtests/api/project-data.spec.tspassed (42). All browser tests, run twice after the last code change: 170 of 171 passed each time. The one failure both times was "a session that ended sends the user to sign in instead of creating a project" (project-failures.spec.ts), which does not touch the requirement form; it passed 3 of 3 when run alone, and is the test already known to be slow under a full parallel run.npm run lintandnpm run typecheckpassed. Run with a temporary config because the dev API held port 5100; the api-project tests on that port and the schema specs were not rerun (no API or schema change). - Known issues and risks: no drag and drop; a long move takes one press per step. Saving a new order raises the requirement's version, so a recorded decision shows as outdated (ADR-038), as for any edit. Screen-reader output was not checked with a screen reader.
- Next step: the evidence count on requirement lists. The AI slice follows ADR-036.
- Branch:
feature/project-ui. Evidence slice 5 is committed (d102562). Committed as643f36a. The approved plan was in~/.claude/plans/yes-i-want-to-delightful-sunset.md. - Completed (ADR-038): a requirement page has a Review section. A project member who did not create the requirement records Accept, Reject, or Request more evidence with a note (required unless accepting). The page shows the current decision, who made it and when, the version and evidence links that were reviewed, a notice when the requirement or its links have changed since, and earlier decisions on demand. The author sees why they cannot review. Requirement lists show each requirement's latest decision, "Not reviewed", or "..., outdated".
- Changed files:
- API:
app/api/Requirements/{ReviewEndpoints,RequirementEndpoints}.cs,app/api/Data/{ProductModels,SpecThreadDbContext}.cs,app/api/Program.cs, migration20261008092413_RequirementReviewsand the model snapshot. - Schema:
scripts/generate-requirement-reviews.mjs,docs/schema/requirement-reviews{,-rollback}.sql. - Web:
app/web/src/lib/{reviews,projects,requirements,project-data}.ts,app/web/src/app/projects/review-actions.ts,app/web/src/components/{review-panel,requirement-rows}.tsx,app/web/src/app/projects/[projectId]/requirements/[requirementId]/page.tsx,app/web/src/app/app-shell.css. - Tests:
scripts/test-database.mjs,tests/e2e/reviews.spec.ts,tests/schema/{reviews,evidence,github-repository}.spec.ts,tests/api/{project-data,products}.spec.ts. - Docs: DECISIONS (ADR-038), API, DATABASE, TESTING, and this file.
- API:
- Differences from the plan:
reviewis on the requirement list only, not on the single-requirement response, because the page reads the full list of decisions. The migration tests in the older schema specs were not reordered; the reviews migration stays applied there and their history counts went up by one. - Checks: the full suite (
npx playwright test: browser, api, and schema projects) passed, 267 tests, with no code change after it.npm run lint,npm run typecheck, the Release API build, anddotnet format app/api --verify-no-changes --no-restorepassed. - Known issues and risks:
- Setup: apply the RequirementReviews migration
(
dotnet ef database update --project app/api, API stopped) and restart or redeploy the API. Until then requirement lists and pages fail. - A project with one member cannot record a decision. There is no members
screen (ADR-031). To try it, add a second account with
POST /projects/{projectId}/members(owner,{ email }) or in the database. - No reviewer assignment, notifications, or evidence policy. "My reviews" and Inbox are still previews.
- A refresh that changes a link's state (a pull request merged after acceptance) does not mark the decision outdated; only an edit or a change of links does.
- Not verified against the live database or by a manual two-account run.
- Setup: apply the RequirementReviews migration
(
- Next step: reorder acceptance criteria. Then the evidence count on requirement lists. The AI slice follows ADR-036.
- Branch:
feature/project-ui. Slice 4 is committed (088593d). This entry is uncommitted. The approved plan is in~/.claude/plans/yes-i-want-to-delightful-sunset.md. - Completed (ADR-037): a release can be linked to a requirement by tag or address. Each release shows "Contains N of M linked changes" and lists every linked commit and pull request as Included, Not included, Not merged, or Not checked, from GitHub's history. Commits and merged pull requests show "In release ".
- Changed files:
- API:
app/api/GitHub/{GitHubClient,EvidenceEndpoints}.cs,app/api/Data/{ProductModels,SpecThreadDbContext}.cs, migration20261008090129_EvidenceReleasesand the model snapshot. - Schema:
scripts/generate-evidence-releases.mjs,docs/schema/evidence-releases{,-rollback}.sql. - Web:
app/web/src/lib/evidence.ts,app/web/src/components/evidence-panel.tsx,app/web/src/app/projects/[projectId]/requirements/[requirementId]/page.tsx,app/web/src/app/app-shell.css. - Tests:
scripts/{test-github,test-database}.mjs,tests/support/github.ts,tests/e2e/evidence.spec.ts,tests/schema/{evidence,github-repository}.spec.ts,tests/api/project-data.spec.ts. - Docs: DECISIONS (ADR-037), API, DATABASE, TESTING, and this file.
- API:
- Differences from the plan: the link endpoint's message for an unreadable reference
now mentions release tags.
evidence-actions.tsneeded no change, as expected. - Checks: the evidence API, unit, and evidence browser tests passed together (46).
The full run of all browser tests plus the GitHub API tests then passed (179), and
no code changed after it.
npm run lint,npm run typecheck, the Release API build, anddotnet format app/api --verify-no-changes --no-restorepassed. Run with a temporary config without the test API on port 5100. - Known issues and risks:
- Not run: the api tests that need port 5100, the older schema specs, and the real
GitHub. Two details come from GitHub's documentation only: resolving a tag
through
commits/tags/<tag>, and the compare statuses. - Setup: apply the EvidenceReleases migration
(
dotnet ef database update --project app/api) and restart or redeploy the API. - Refresh makes one more GitHub call per release and per release-change pair.
- "Included" is ancestry: a reverted change still counts.
- Not run: the api tests that need port 5100, the older schema specs, and the real
GitHub. Two details come from GitHub's documentation only: resolving a tag
through
- Next step: the review decision (accept, reject, request more evidence, with a note). Then reordering criteria and the evidence count on lists. The AI slice follows ADR-036.
- Branch:
feature/project-ui. Slices 1 to 3 are committed (94759df). This entry is uncommitted. The approved plan is in~/.claude/plans/yes-i-want-to-delightful-sunset.md. - Completed:
- Check results (ADR-035): a linked pull request or commit shows a line such as "5 of 6 checks passed, 1 failed" that opens to each check with its result in words. Refresh re-reads them.
- Link source (ADR-036): every evidence link is stored as
manualorsuggested. Nothing createssuggestedyet. The ADR sets the rules for the later AI work.
- Changed files:
- API:
app/api/GitHub/{GitHubClient,EvidenceEndpoints}.cs,app/api/Data/{ProductModels,SpecThreadDbContext}.cs, migration20261008084108_EvidenceChecksand the model snapshot. - Schema:
scripts/generate-evidence-checks.mjs,docs/schema/evidence-checks{,-rollback}.sql. - Web:
app/web/src/lib/evidence.ts,app/web/src/components/evidence-panel.tsx,app/web/src/app/projects/[projectId]/requirements/[requirementId]/page.tsx,app/web/src/app/app-shell.css. - Tests:
scripts/{test-github,test-database}.mjs,tests/support/github.ts,tests/e2e/{evidence,project-failures}.spec.ts,tests/schema/{evidence,github-repository}.spec.ts,tests/api/project-data.spec.ts. - Docs: DECISIONS (ADR-035, ADR-036), API, DATABASE, TESTING, and this file.
- API:
- Differences from the plan: none in behavior. A check's link is kept only when it is on github.com, as planned, which means statuses from outside CI services are listed without a link.
- Checks: the evidence API, unit, and evidence browser tests passed together (42).
In the full run of all browser tests plus the GitHub API tests, 174 passed and one
failed: "a session that ended sends the user to sign in". That test waits for a
multi-step redirect and timed out after 5 seconds under load; its wait was raised
to 15 seconds and its file then passed three times in a row. The full run was not
repeated after that change.
npm run lint,npm run typecheck, the Release API build, anddotnet format app/api --verify-no-changes --no-restorepassed. Run with a temporary config without the test API on port 5100. - Known issues and risks:
- Not run: the api tests that need port 5100, the older schema specs, and the real GitHub.
- Setup: apply the EvidenceChecks migration
(
dotnet ef database update --project app/api) and restart or redeploy the API before the requirement page works. - Refresh makes more GitHub calls than before and slows down as links grow.
- Next step: releases (link a release tag). Then the review decision, reordering criteria, and the evidence count on lists. The AI slice follows ADR-036.
- Branch:
feature/project-ui. Uncommitted, together with slice 2 below. - Completed (ADR-034): a commit can be linked to a requirement by SHA or address and shows its message, author, date, and lines and files changed. A linked pull request shows its totals and lists its commits on demand.
- Changed files beyond slice 2:
app/api/GitHub/{GitHubClient,EvidenceEndpoints}.cs,app/api/Data/{ProductModels,SpecThreadDbContext}.cs, migration20261008082151_EvidenceCommitsand the model snapshot,scripts/generate-evidence-commits.mjs,docs/schema/evidence-commits{,-rollback}.sql,app/web/src/lib/evidence.ts,app/web/src/components/evidence-panel.tsx,app/web/src/app/app-shell.css,scripts/{test-github,test-database}.mjs,tests/support/github.ts,tests/e2e/evidence.spec.ts,tests/schema/{evidence,github-repository}.spec.ts,tests/api/project-data.spec.ts, and docs/{DECISIONS,API,DATABASE,TESTING,HANDOFF}.md. - Checks: 155 browser tests and the 15 evidence and repository API tests passed in one
run; the project-data unit tests passed in the run before the last database-rule
fix, which did not touch them. Run with a temporary config without the test API on
port 5100.
npm run lint,npm run typecheck, the Release API build, anddotnet format app/api --verify-no-changes --no-restorepassed. - Known issues and risks:
- Not run: the api tests that need port 5100, the older schema specs, and the real GitHub.
- Setup: apply the pending migrations (RequirementEvidence, then
EvidenceCommits;
dotnet ef database update --project app/apidoes both) and restart or redeploy the API before the requirement page works. - A test found that the first version of the new check constraint allowed a commit with no SHA and an issue with no number; the constraint was corrected before the migration was ever applied.
- Next step: check results for a linked pull request, then releases. After evidence, the three follow-ups listed below (review decision, reordering criteria, evidence count on lists).
- Branch:
feature/project-ui. Slice 1 below is committed (b062d13). This entry is uncommitted. - Completed (ADR-033): a requirement page has an Evidence section. Members link an issue or pull request from the connected repository by number or address, see the items as a timeline with state and author as GitHub reported them, refresh them from GitHub, and remove a link.
- Changed files:
- API:
app/api/GitHub/{EvidenceEndpoints,GitHubClient,RepositoryEndpoints}.cs,app/api/Program.cs,app/api/Data/{ProductModels,SpecThreadDbContext}.cs, migration20261008073621_RequirementEvidenceand the model snapshot. - Schema:
scripts/generate-requirement-evidence.mjs,docs/schema/requirement-evidence{,-rollback}.sql. - Web:
app/web/src/lib/{evidence,project-data}.ts,app/web/src/app/projects/evidence-actions.ts,app/web/src/components/{evidence-panel,repository-connect}.tsx,app/web/src/app/projects/[projectId]/requirements/[requirementId]/page.tsx,app/web/src/app/app-shell.css. - Tests:
tests/e2e/{evidence,repository}.spec.ts,tests/schema/{evidence,github-repository}.spec.ts,tests/api/project-data.spec.ts,tests/support/{github,api-process}.ts,scripts/{test-github,test-database}.mjs. - Docs: DECISIONS (ADR-033), API, DATABASE, TESTING, and this file.
- API:
- Checks: 154 browser tests and the 13 evidence and repository API tests passed in one
run, and the project-data unit tests passed, with a temporary config that left out
the test API on port 5100, which the user's dev API held.
npm run lint,npm run typecheck, the Release API build, anddotnet format app/api --verify-no-changes --no-restorepassed. - Known issues and risks:
- Not run: the api tests that need port 5100, the older schema specs, and the real GitHub. The user connected a real repository in slice 1; linking has only been tried against the stand-in.
- Setup before it works locally or in production: apply the RequirementEvidence migration (docs/DATABASE.md), then restart or redeploy the API. Until then a requirement page shows not-found (old API) or the error page (missing table).
- Evidence does not update on its own; someone presses Refresh.
- Two fixes found by tests: a refused repository connect no longer clears the chosen repository, and test API instances no longer pick up a developer's user-secrets.
- Next step: slice 3, commits and check results for a linked pull request, then slice 4, releases. After evidence, the three follow-ups listed below (review decision, reordering criteria, evidence count on lists).
- Branch:
feature/project-ui. Uncommitted, on top of the uncommitted requirements work and members removal described below. - Completed (ADR-032): the owner connects one GitHub repository to a project in Settings > Repository, through the GitHub App, and can disconnect it. The connection shows in the project's details panel and Settings.
- Changed files:
- API:
app/api/GitHub/{GitHubClient,RepositoryEndpoints}.cs,app/api/Program.cs,app/api/Data/{ProductModels,SpecThreadDbContext}.cs, migration20261008070130_ProjectRepositoriesand the model snapshot. - Schema:
scripts/generate-project-repositories.mjs,docs/schema/project-repositories{,-rollback}.sql. - Web:
app/web/src/lib/{repositories,github-data}.ts,app/web/src/app/projects/repository-actions.ts,app/web/src/components/repository-connect.tsx,app/web/src/app/projects/[projectId]/settings/{page,repository/page}.tsx,app/web/src/app/projects/[projectId]/page.tsx,app/web/src/app/app-shell.css. - Tests:
scripts/{test-github.mjs,test-github.d.mts,start-test-web.mjs,test-database.mjs},tests/support/github.ts,tests/e2e/repository.spec.ts,tests/schema/github-repository.spec.ts,tests/api/{project-data,products}.spec.ts,playwright.config.ts(dummy GitHub client values for the test web app). - Docs: DECISIONS (ADR-032), API, DATABASE, DEPLOYMENT, TESTING, and this file.
- API:
- Checks: all 144 browser tests, the 7 repository API tests, and the project-data unit
tests passed, run with a temporary config that left out the test API on port 5100,
which the user's dev API held.
npm run lint,npm run typecheck, the Release API build, anddotnet format app/api --verify-no-changes --no-restorepassed. - Known issues and risks:
- Not run: the api tests that need port 5100 (including the edited
tests/api/products.spec.ts), the other schema specs, and the real GitHub. - Local and production setup is needed before project pages work again: apply the ProjectRepositories migration, restart or redeploy the API, and set the GitHub settings (docs/DEPLOYMENT.md). Until then project pages show not-found, because the running API has no repository endpoint.
- Codex's teams branch will add its own migration; the two need ordering when the branches meet.
- Not run: the api tests that need port 5100 (including the edited
- Next step: slice 2, linking issues and pull requests to a requirement. Then the three follow-ups listed in the next entry.
- Branch:
feature/project-ui, fast-forwarded tofeature/visual-polishat4fc3492and pushed. The two branches are the same up to that commit. The changes in this entry are uncommitted. No PR is open. - Completed (ADR-030):
- The Requirements tab has "New requirement". Create and edit share one form for title, description, and ordered acceptance criteria.
- A requirement page shows the description, criteria, version, and author, with Edit and a confirmed Archive.
- A save is refused when someone else saved first, and the message says so.
- Archived requirements and archived projects are read-only.
- Changed files:
- Web:
app/web/src/lib/{requirements,project-data,projects}.ts,app/web/src/app/projects/requirement-actions.ts,app/web/src/app/projects/[projectId]/requirements/{page,new/page}.tsx,.../requirements/[requirementId]/{page,edit/page}.tsx,app/web/src/components/{requirement-form,requirement-archive}.tsx,app/web/src/app/app-shell.css, andapp/web/src/app/projects/actions.ts(isProjectIdrenamed toisUuid). - Tests:
tests/e2e/requirements.spec.ts(new, 24 tests),tests/api/project-data.spec.ts,tests/e2e/scaffold.spec.ts. - Docs: DECISIONS (ADR-030), TESTING, and this file.
- Web:
- Checks: all 119 browser tests passed, run with a temporary config that started only
the test web server because the user's dev API held port 5100.
npm run lintandnpm run typecheckpassed. Inspected screenshots of the form and the detail page. - Known issues and risks:
- The full
npm testwas not run as configured. In the temporary run the api and schema tests that need the test token issuer on port 5101 could not start; the new unit tests intests/api/project-data.spec.tsdid run and passed. - Criteria cannot be reordered. Text typed before the page finishes loading is reset.
- A mistaken text replace touched files in
app/web/.next; the build cache was cleared. Ifnpm run devmisbehaves, stop it, deleteapp/web/.next, and restart. - The project Members tab and pages were removed at the user's request (ADR-031): projects will belong to teams, and team onboarding is being built with Codex on a separate branch.
- In one full browser run, two tests failed once ("Try again recovers" and "a member creates a requirement") and then passed in two repeated runs of those files. They look timing-sensitive under load and were not changed.
- The full
- Next step: the evidence slice with a real GitHub connection, chosen by the user. Its
design needs the user's approval and GitHub App details before any code. After
evidence, the user asked for these three, one prompt at a time:
- A review decision on a requirement (accept, reject, or request more evidence, with a note).
- Reordering acceptance criteria in the form.
- An evidence count on the requirement lists.
- Branch:
feature/visual-polish, committed as4fc3492. - Completed:
- The landing, sign-in, password, sign-in error, and policy pages now use the black and white palette (ADR-027). The brand mark is shown in white.
- Planned pages are unchanged and still labeled as previews.
- Failure handling (ADR-029): "Try again" fetches again, a failing project section keeps the project frame, and a form submitted after the session ended goes to sign-in.
- A test-only API proxy lets browser tests make the API fail for one user, with 22 new failure tests.
- Changed files:
app/web/src/app/{landing,public-pages,app-shell}.css,app/web/src/app/error.tsx,app/web/src/app/projects/[projectId]/error.tsx(new),scripts/{test-api-proxy,start-test-web}.mjs,tests/support/api-faults.ts(new),tests/e2e/project-failures.spec.ts(new), and docs/{DECISIONS,TESTING,HANDOFF}.md. - Checks: all 95 browser tests passed, run with a temporary config that started only
the test web server because the user's dev API held port 5100.
npm run lintandnpm run typecheckpassed. Inspected screenshots of the landing, login, and sign-in error pages. - Known issues and risks:
- The full
npm test(api and schema projects) was not run in this session. - The browser icon is still the lavender mark.
- The public pages were recolored by replacing color values; their hover and focus states were not inspected one by one.
- The full
- Next step: the user reviews. Then build creating and editing requirements inside the Requirements tab.
- Branch:
feature/visual-polish, created fromfeature/project-uiatb47ce88. Changes are uncommitted. It should merge afterfeature/project-ui. The user asked for design and the project workspace together, so both are on this branch. - Completed:
- Visual system (ADR-027): near-black with white as the accent, the sidebar on the page background, and the content in an inset rounded panel. Pills for view switches and tabs, white primary buttons, one row-list style, dark form fields.
- Dashboard: the row of evidence circles is replaced by a progress ring with a count and a checklist in the opened row. Its header action is now "New project". It still shows labeled sample data.
- Project workspace (ADR-028): a layout with breadcrumb and tabs for every
/projects/{id}page. Overview, Requirements, and Members read real data. Settings lets the owner rename and archive. Creating a project opens it. - Example-project links are removed from the sidebar, the dashboard, and planned-page navigation.
- Changed files:
- Web styles and shell:
app/web/src/app/app-shell.css,app/web/src/components/{app-frame,workspace-sidebar,dashboard-preview,scaffold-page,account-panel,project-form}.tsx,app/web/src/app/{error,not-found}.tsx. - Project workspace:
app/web/src/app/projects/[projectId]/{layout,loading,page}.tsx,.../[projectId]/{requirements,members,settings}/page.tsx,app/web/src/components/{project-tabs,project-settings,requirement-rows}.tsx,app/web/src/lib/{project-data,projects,scaffold-routes}.ts,app/web/src/app/projects/{page,loading,actions}.ts(x),app/web/src/app/projects/new/page.tsx. - Tests:
tests/e2e/{projects,scaffold,home}.spec.ts,tests/e2e/fixtures.ts(addsrunTestSql),tests/api/project-data.spec.ts. - Docs: DECISIONS (ADR-027, ADR-028), TESTING, and this file.
- Web styles and shell:
- Decisions and assumptions: ADR-027 and ADR-028. No API, schema, or package change.
- Checks: all 74 browser tests and the 7 project-data and API-config unit tests passed,
run with a temporary config that started only the test web server because the user's
dev API held port 5100.
npm run lint,npm run typecheck, andgit diff --checkpassed. Inspected desktop and 390px screenshots of the dashboard, project overview, members, settings, and a planned section. - Known issues and risks:
- The full
npm testwas not run; the rest of the api project and the schema project were not re-run. No file they cover changed. - The sidebar's "Example team" links and the dashboard rows are still sample content.
- Requirement rows link to the requirement page, which is still a planned placeholder.
- A project's not-found page is sent with HTTP 200 (ADR-028).
- The full
- Next step: the user reviews the look and the workspace. Then build creating and editing requirements inside the Requirements tab.
- Branch:
feature/project-ui, created frommainat11285c2. Changes are uncommitted. - Scope agreed with the user: projects only (list, create, then an overview with rename and archive), built in slices that the user confirms. This entry covers the first slice.
- Completed:
/projectslists the signed-in user's active projects from the API, with an empty state and a link to create one./projects/newcreates a personal project through a server action and returns to the list. A rejected name shows a message next to the field.- Browser tests now run against a real API:
scripts/start-test-web.mjsstarts one on port 5106 with the web test database and the test web app as token issuer.
- Changed files:
- Web:
app/web/src/lib/projects.ts,app/web/src/app/projects/{page,loading,actions}.ts(x),app/web/src/app/projects/new/page.tsx,app/web/src/components/project-form.tsx,app/web/src/app/app-shell.css. - Tests:
scripts/start-test-web.mjs,tests/e2e/projects.spec.ts(new),tests/api/project-data.spec.ts(new),tests/e2e/scaffold.spec.ts. - Docs: DECISIONS (ADR-026), TESTING, and this file.
- Web:
- Decisions and assumptions: ADR-026. Creating a project has no team choice because the API has no teams. After creating, the user returns to the list, because the overview page is still a placeholder. The scaffold test for the personal/team project descriptions was removed with those placeholders. No API, schema, or package change.
- Checks:
npm test(131 passed),npm run lint, andnpm run typecheckpassed. Inspected desktop and mobile screenshots of the list and the form error. - Known issues and risks:
- Not exercised: an unreachable API, a non-400 failure from the create call, and the loading state.
- Project rows link to
/projects/{id}, which is still a placeholder. - The dashboard and the sidebar's "Example team" still show sample data.
- Production needs
SPECTHREAD_API_URLin Vercel and a Render deploy of the mergedmainbefore these pages work there. Neither was checked. The deployment notes in the next entry still apply.
- Next step: the user reviews this slice. Then build the project overview at
/projects/{id}with rename and archive, and send the create form there.
- Branch:
feature/teamsin/workspace/SpecThread, based on11285c2. Cloud workspace. The user explicitly authorized committing each slice and opening a GitHub PR. Feature commits cover onboarding/navigation, members/ settings, team projects/archive restoration, and invitations, followed by documentation and review screenshots. No deployment, live mail, or shared database migration has been authorized or run. - User requires questions/options before substantive UI/feature decisions. They supplied navigation screenshots, paused earlier work, selected the revised behavior, and explicitly approved "Go ahead with the revised Teams plan." Do not end an active turn while asynchronous design answers are pending.
- Claude owns
feature/visual-polish, global/projectspages, and project creation/deletion forms. This branch leaves those web files untouched and owns Teams UI, team-specific project/archive tables, and C# team access contracts. - Confirmed and implemented (ADR-040 supersedes earlier navigation/personal projects):
- Your teams: independently expandable groups with account-saved state, Home/Projects links, personal favorites first, and a real native team menu. Menu: Favorite/Unfavorite, Settings, Copy URL, Open archive, Leave team.
/teams: searchable compact rows of real memberships. Normal creation is/teams/new, name/optional description, Create/Cancel, creator becomes Owner.- Team Home: Overview/Members tabs; name/description in main area and members plus quick links on the right. Documents is separately agreed future work.
- After first verified sign-in, required full-page onboarding asks for initial team name/optional description. It resumes across routes and sessions. Initial team, Owner membership, and persistent completion commit atomically. Duplicate initial submissions yield one 201/one 409 with no extra team. Completion survives leaving/removal and is never inferred from cookies or current membership.
- All projects belong to one team; every Member accesses all team projects and works on requirements. Owner/Admin alone create and manage names/settings/ archive/restore. Legacy migration preserves access with one team per project, carrying over owner and collaborators; old project-membership writes return 410.
- Team Projects uses compact name/active-requirement-count/creation-date rows. Archive contains only the team's archived projects. The user confirmed restore in archive rows, Owner/Admin only, with confirmation naming project and team. Restoration refreshes archive/active lists and rechecks live permissions.
- Members: name/email/role/joined table. Owner-only role dropdown + Save; Admins remove regular Members, Owner alone removes Admins, nobody removes Owner. Named confirmations guard removal/leave. Owner transfers to any existing member before leaving; previous Owner becomes Admin. Settings is one page: name/description Save, ownership transfer, Leave. Members see settings read-only.
- Invitations: Invite people email/role dialog from Members; separate View invitations table of email/role/inviter/expiry/status, Resend/Revoke. Owner manages Admin/Member invites; Admin manages Member invites only. Email plus immediate Copy link; seven-day expiry; resend rotates secret and issuer. Current inviter permission is checked at acceptance. Joining always requires acceptance by a verified account matching the email. Accepted membership, invitation consumption, and onboarding completion commit together. New signup acceptance joins the invited team without naming another first team.
- Acceptance is the confirmed focused full-page screen matching onboarding. It shows team, inviter, invited email, role, expiry, and Accept. Sign-in/signup/ verification preserve destination. Wrong accounts can sign out and switch. Expired/revoked/replaced/permission-invalid links cannot join. Viewing a link never unlocks onboarding. Consumed links cannot rejoin removed members.
- Implementation boundaries:
- C# owns product rules and persistence; Next.js server-only JWT API calls and authenticated server actions own UI orchestration. Browser receives no API JWT. Only exact 64-hex invitation preview paths and legacy expiry redirects are public; other unknown invitation URLs retain the deny-by-default gate.
- Team management, invitations, and project-management writes serialize on the team row, re-read permissions/state, and form the response before commit. Invitation storage contains only SHA-256 hashes of 32-byte random secrets. Concurrent accepts in different teams use an idempotent completion UPSERT.
- Existing email sender is reused. Delivery failure preserves the usable invite and Copy link/retry. API hosting request-start/finish logs are filtered below Warning to avoid raw invitation URL secrets; public preview disables caching and page metadata disables referrers/indexing. No live emails sent.
- EF-only Teams, TeamNavigationOnboarding, TeamProjects, and TeamInvitations migrations and documented generators emit reviewed forward/rollback SQL, RLS, and revoked browser grants. Only disposable test databases receive them. Invitation rollback drops records/links but preserves accepted membership and completion. See DATABASE.md for legacy-project rollback reconciliation limits.
- Named native dialogs supply focus containment/Escape/cancel; mobile tables scroll locally. Screenshots were reviewed for modal centering, Save contrast, invitation table wrapping, and focused mobile acceptance.
- Final verification (all sessions closed):
- Complete Playwright suite: 165 passed (3.4m) on the final source, log
/tmp/specthread-teams-ready.log. It builds the Release API and production web. Covers browser flows, real signup/verification, permissions/concurrency, JWT, onboarding, inherited project access, migrations, RLS/grants, and rollback. npm run lintandnpm run typecheck: passed after the final form correction.dotnet format app/api --verify-no-changes --no-restore: passed. Offline EF pending-model check and full-suite snapshot consistency check passed.git diff --check: passed. Global/projectsweb diff is empty.- Commit checkpoints: onboarding and project EF snapshots were regenerated
with
dotnet ef migrations remove --forcein an isolated copy using an unreachable placeholder connection, without changing the tested working files. Intermediate C# builds, web lint/type checks, and offline EF model checks passed. SQL generators normalize the final newline; regenerated SQL and the complete staged patch passgit diff --check. - Focused invitation/member form checks: 6 passed (2.2m), log
/tmp/specthread-team-form-retry.log. Retry testing found React's native reset reverted an Admin selection after a rejected invitation; the dialog and member role forms deliberately prevent that reset. The final browser flow checks both email/role retention and successful retry/acceptance. Earlier failing runs were corrected; the final complete run includes the regression.
- Complete Playwright suite: 165 passed (3.4m) on the final source, log
- Browser: official Chrome 155 extracted under
/workspace/.cache/teams-browser, temporary config/workspace/.setup-tools/playwright-teams-chrome.config.ts. Pinned Playwright Chromium remains blocked at storage.googleapis.com despite the user's saved allowlist update. Repository defaults unchanged. No tests use live Supabase/OAuth/mail. Screenshots are copied before subsequent runs to/workspace/.cache/teams-preview/, including navigation, onboarding, members, transfer, invite dialog/list, mobile acceptance, and mobile restoration. Selected screenshots using only disposable test accounts are also committed underdocs/reviews/teams/for GitHub review. - Changed areas: API Data/Teams/Projects/Program/migrations; web teams/onboarding/ invitation pages, server actions, AppFrame/sidebar/proxy/API helper, local team components/styles; migration generators/SQL, disposable harness/fixtures, API/ schema/browser tests, and API/database/project/architecture/deployment/testing/ decision/handoff docs. Global project web page diff remains empty.
- Still outside the agreed initial Home scope: Documents, Activity/audit history, and Claude's global project UI. Do not invent these or add tabs without asking.
- Exact next step: review the
feature/teamsPR againstmainand its screenshots. Coordinate Claude's project UI with the documentedteamId/teamRoleAPI contract before integrating branches. Merge only through the reviewed GitHub PR. No pending design questions, shared migration, deployment, or live-mail check.
- Branch:
fix/archive-timestamp-precision, merged intomainthrough PR #13. - Problem: CI failed in
tests/schema/product-api.spec.tsbecause the first archive response carriedDateTime.UtcNowat 100 ns precision, while a repeat request returned the stored value, which PostgreSQL keeps at microsecond precision. - Completed:
Clock.UtcNow()inapp/api/Data/Clock.csdrops the sub-microsecond digit. All six places that stamp a row use it (project create and archive, member add, requirement create, update, and archive), so a write response matches later reads. - Changed files:
app/api/Data/Clock.cs(new),app/api/Projects/ProjectEndpoints.cs,app/api/Projects/MemberEndpoints.cs,app/api/Requirements/RequirementEndpoints.cs,tests/schema/product-api.spec.ts, and this file. - Decisions and assumptions: timestamps are still generated by the API, not the database. No schema change, migration, new package, or CI change.
- Checks:
- Before the fix, the spec failed locally with the same mismatch on
createdAt. - Passed after the fix:
npm test(125 passed),npm run lint,npm run typecheck,dotnet build app/api --configuration Release,dotnet format app/api --verify-no-changes --no-restore, andgit diff --check.
- Before the fix, the spec failed locally with the same mismatch on
- Known issues and risks:
joinedAtuses the same clock but has no assertion comparing the add response with the list.
- Branch:
feature/requirements-api, created fromorigin/mainatf41acc2. Changes are uncommitted. The pre-existing uncommitted deletion ofapp/api/.env.exampleis unrelated to this task and was left untouched. - Completed:
- API endpoints for projects, requirements, and acceptance criteria. Members read and edit requirements. Only the owner renames or archives a project. Non-members get 404. A stale version or an archived item returns 409. Validation returns 400 with the failing fields (ADR-024).
- The server-only web helper
apiFetchsends the user's Better Auth JWT to the API atSPECTHREAD_API_URL. - docs/API.md is the contract summary for frontend developers.
- Member management (ADR-025): GET, POST, and DELETE
/projects/{id}/members. The owner adds an existing account by its verified email; members can leave; the owner can't be removed.
- Changed files:
- API:
app/api/Program.cs,app/api/Projects/ProjectAccess.cs,app/api/Projects/ProjectEndpoints.cs,app/api/Projects/MemberEndpoints.cs,app/api/Requirements/RequirementEndpoints.cs. - Web:
app/web/src/lib/api.ts,app/web/src/lib/api-config.ts,app/web/.env.example. - Tests:
tests/schema/product-api.spec.ts,tests/api/products.spec.ts,tests/api/api-config.spec.ts. - Docs: docs/API.md (new), DECISIONS (ADR-024, ADR-025), ARCHITECTURE, TESTING, DEPLOYMENT.
- API:
- Decisions and assumptions (ADR-024):
- Validation limits are new.
- Updates replace the whole criteria list, so criterion IDs change on every save.
- Browsers never call the API directly, so CORS is not configured.
- No schema change, migration, or new package.
- Checks:
- Passed:
dotnet build app/api --configuration Release,dotnet format app/api --verify-no-changes --no-restore,npm run lint,npm run typecheck, andgit diff --check. npm test: 125 passed, including the 10 new product API and member tests against Docker Postgres.npm ciwas needed because the mergedmainaddedlucide-react.
- Passed:
- Known issues and risks:
- Invitations for people without accounts, ownership transfer, teams, unarchiving, and audit events do not exist yet.
- Add-by-email reveals to owners whether an address has a verified account. The trade-off is accepted in ADR-025. Member lookups are not rate limited.
- The concurrent-save race path (
DbUpdateConcurrencyException) is not exercised. - No UI uses the API yet.
- No live Supabase writes were performed.
- Deployment: none of this blocks the Vercel build.
apiFetchis not imported by any page, andSPECTHREAD_API_URLis read only whenapiFetchis called. Before pages call the API:- Vercel: set
SPECTHREAD_API_URL=https://specthread-api.onrender.comfor Production. - Preview deployments: tokens carry the preview's origin as issuer and audience
(Better Auth uses
BETTER_AUTH_URL). The Render API trusts only its singleAuth__Issuer, so API calls from previews return 401. Either run a separate preview API with a matching issuer, or accept that API-backed pages work only in production. - Render:
Auth__Issuermust equal Vercel'sBETTER_AUTH_URLexactly, andConnectionStrings__Databasemust be set. Otherwise requests return 500. The new endpoints exist only after Render redeploys from the mergedmain. - Database role: product tables have RLS enabled with no policies. The API must
connect as the table-owning role (
postgresthrough the session pooler, as in the verified probe). Another role would get empty lists and failing writes. - Render free-plan cold starts can take most of a minute.
apiFetchhas no timeout, so pages need a loading state, or move the API to a paid plan. - GitHub sign-ins whose email GitHub has not verified are stored unverified, so they cannot be added as project members (ADR-025).
- The ADR-015 EdDSA key expiry is complete, as confirmed by the user on 2026-10-01.
- Vercel: set
- Next step: review the diff and commit with approval, then open a PR to
main. After merging, setSPECTHREAD_API_URLin Vercel. Follow-up tasks: wire the projects and requirement pages toapiFetch, and build invitations for people without accounts.
- Branch:
coderabbit/improve-docstring-coverage/84e64e39; uncommitted changes based on verified PR head4702b29280c0b0cbac524873197247c66d0d2855. - Added 14 JSDoc comments in
app/web/src/components/landing-page.tsxandapp/web/src/components/auth-form.tsx; no executable changes or new dependencies. - Local TypeScript AST audit of named functions intersecting PR hunks: 54/64 documented (84.38%). This approximates the hosted check, which counted 62 functions; its result must be confirmed after publication.
- Comment-stripped TypeScript compilation matched the PR head for all 37 changed TypeScript files. Behavior tests were skipped for this documentation-only patch.
- Validation:
npm run lint,npm run typecheck, andgit diff --checkpassed.npm run buildpassed with temporary loopback auth configuration (random secret, offline placeholder database URL, email logging, and disabled OAuth providers). Restored missing sandbox dependencies withnpm ci --no-audit --no-fund. - CodeRabbit review could not run because it is disabled for this coding task.
- Next step: publish the documentation changes with approval and rerun PR #8's hosted Docstring Coverage check. No application behavior or architectural decisions changed.
- Branch:
scaffolding; builds on commit51432b0. Changes are uncommitted. - Completed:
- Login and signup use the user-supplied Claude Design layout: the form column with its own logo and footer, and an animated evidence-thread panel. The panel loops scattered → gathered → accepted and holds on "accepted" when reduced motion is preferred.
- Existing behavior is kept:
- email, Google, and GitHub sign-in (ADR-016);
- error and verification states;
nextreturn.
- On narrow screens the panel is hidden and the form stacks.
- The three design files (
AuthPage.tsx,LandingPage.tsx,RequirementsSidebar.tsx) were deleted after integration.
- Changed files:
app/web/src/components/{auth-form,sign-in-thread,app-frame,landing-page}.tsxapp/web/src/app/landing.csstests/e2e/{auth,home,protection}.spec.ts
- Decisions and assumptions:
- The design's graphite palette matches the landing tokens, so the sign-in
styles live in
landing.cssunder the.landingclass. - The design's theme, motion-speed, and atmosphere options were not carried over, since only the defaults are used.
- Google sign-in was added beside GitHub, per ADR-016.
- The broken
/docsfooter link was dropped. - The email label stays "Email", not "Work email".
- The signup password keeps its visible hint instead of a placeholder.
- The forgot-password, reset, and sign-in error pages keep the previous layout.
- The design's graphite palette matches the landing tokens, so the sign-in
styles live in
- Verification:
npm run lint,npm run typecheck, andgit diff --checkpassed.npm testpassed, 114 tests.- Inspected desktop screenshots of the login page in the scattered and accepted phases, the signup page, and a mobile screenshot of signup. There were no console errors and no horizontal scroll.
- Removed a timing-dependent dashboard logo assertion from
home.spec.ts. A signed-in user sees initials there, not the logo.
- Known issues: none new.
- Exact next step: the user reviews, then commit after explicit approval.
- Branch:
scaffolding; builds on commit58ea223. Changes are uncommitted. - Completed:
- The deny-by-default
app/web/src/proxy.tsvalidates the Better Auth session for every page except/,/login,/signup,/forgot-password,/reset-password,/auth/error,/privacy, and/terms. - Signed-out visitors are redirected to
/login?next=<path and query>. safeNextPathaccepts only same-site paths. Email, social, and verification sign-in all return tonext.- Signed-in visitors to login and signup go straight to
next. - The dashboard-preview link on the sign-in pages is removed.
- The settings sidebar always links "Back to app".
- Browser tests run signed in by default through
tests/e2e/fixtures.ts, using a real seeded session.
- The deny-by-default
- Changed files:
app/web/src/proxy.tsapp/web/src/lib/app-navigation.tsapp/web/src/app/{login,signup}/page.tsxapp/web/src/components/{auth-form,settings-sidebar}.tsxtests/e2e/{fixtures,protection,auth,home,landing,scaffold,shell}.spec.ts(fixtures.tsis not a spec)README.mdanddocs/{ARCHITECTURE,DECISIONS,TESTING,HANDOFF}.md
- Decisions and assumptions:
- Recorded in ADR-023, which supersedes the public dashboard in ADR-019 and ADR-020.
- The spec and plan are in
docs/superpowers/{specs,plans}/2026-09-29-route-protection*, which.gitignoreignores. - The C# API is unchanged. It already requires a JWT on every endpoint except
/healthand development OpenAPI.
- Verification:
npm run lint,npm run typecheck, andgit diff --checkpassed.npm testpassed, 111 tests.- A signed-out probe of the dev server returned 307 to
/login?next=%2Fdashboardfor/dashboard. It returned 307 to/login?next=%2Fteams%3Ftab%3Dmembersfor/teams?tab=members./icon.png/xwas also redirected to login. /,/privacy,/terms,/login,/thread-mark.png, and/icon.pngreturned 200, and/aboutstill redirected to/#about.- A fresh reviewer checked the whole change and found no bypass or open
redirect. The fixes it prompted are in:
- the proxy now forwards Better Auth's refreshed session cookie, so active users are not logged out after 7 days;
safeNextPathis at least as strict as Better Auth'scallbackURLcheck;- the matcher's image exclusions are anchored;
- ARCHITECTURE.md is updated.
- Known issues:
- API authorization (project and team membership checks) is still unimplemented. It belongs with the data features.
- Deferred review minors:
- The profile menu's "Log in" link and
/settings/account's fallback redirect omitnext. auth-formshows "verify your email" for any 403.- The return-to test does not include a query string.
- The profile menu's "Log in" link and
- At teardown the web server logs pool errors when the test database stops. This does not affect any test.
- Each protected page request performs one session lookup.
- Exact next step: the user reviews, then commit and push to the existing PR only
after explicit user approval. Merge into
mainthrough the pull request.
- Branch:
scaffolding; builds on commitc173d61, the sidebar task below. Changes are uncommitted. - Completed:
- The landing page uses the user-supplied design from Claude Design, moved to
components/landing-page.tsxwith its styles inlanding.css. - About (new copy drawn from
docs/PROJECT.md) and How it works are sections below the hero. - The animations work: the hero table (with a pause control), evidence gathering with Replay, and the review decision. All three respect reduced motion.
- The page adapts to narrow screens.
/aboutand/about/how-it-worksredirect to landing sections.- Privacy and Terms are public pages at
/privacyand/terms; the old/about/*addresses redirect there. - The settings sidebar dropped its "Help & about" group; Help moved to "Getting started".
- Removed
main-navigation.tsx, the four/aboutpages, and the user's unusedRequirementsSidebar.tsx, with the user's approval.
- The landing page uses the user-supplied design from Claude Design, moved to
- Changed files:
app/web/next.config.ts(redirects)app/web/src/app/{page.tsx,landing.css,privacy/page.tsx,terms/page.tsx}app/web/src/components/{landing-page,policy-page,app-frame,settings-sidebar}.tsxapp/web/src/lib/{app-navigation,scaffold-routes}.tstests/e2e/{landing,home,shell,scaffold}.spec.tsREADME.mdanddocs/{DECISIONS,TESTING,HANDOFF}.md
- Decisions and assumptions:
- Recorded in ADR-022.
- Only the design's dark, left-aligned variant is kept.
- The design's broken
/docsfooter link was dropped. - About copy is a draft for the user to edit.
- Verification:
npm run lint,npm run typecheck, andgit diff --checkpassed.npm testpassed, 100 tests.- Inspected desktop and mobile screenshots of the hero, About, the evidence thread, the review decision, the mobile menu, and Privacy. There were no console errors and no horizontal scroll.
- Known issues:
- Application routes such as
/dashboardand/settingsare still public by URL. Real route protection is separate work. - Policy pages are placeholders.
- The deferred minors listed in the sidebar task below still apply.
- Application routes such as
- Exact next step: the user reviews the landing page. Then commit and push to
the existing PR, only after explicit user approval. Merge into
mainthrough the pull request.
- Branch:
scaffolding; committed asc173d61. - Completed:
- Routes pick one of three frames through
frameForinlib/app-navigation.ts, following ADR-021. - Landing and sign-in pages keep the top header.
- Settings, account, help, about, welcome, onboarding, and invite pages use a
grouped settings sidebar. Its top link is "Back to app" (
/dashboard) for signed-in users and "Back to home" (/) for signed-out visitors. - Every other route uses the workspace sidebar, including the 404 page.
- A profile menu at the top of the workspace sidebar offers Settings, Account, and Log out, or Settings, Log in, and Sign up when signed out.
- The account page moved to
/settings/account, and/accountredirects there./settingsis now titled "Preferences". - Removed the public
MainNavigation, its CSS, and the bottom sidebar links.
- Routes pick one of three frames through
- Changed files:
app/web/src/components/{app-frame,workspace-sidebar,settings-sidebar,app-nav-link,profile-menu,main-navigation,account-panel}.tsxapp/web/src/lib/{app-navigation,scaffold-routes}.tsapp/web/src/app/{account,settings,settings/account}/page.tsxapp/web/src/app/{app-shell,public-pages}.csstests/e2e/{shell,auth,scaffold}.spec.tsREADME.mdanddocs/{DECISIONS,DEPLOYMENT,TESTING,HANDOFF}.md
- Decisions and assumptions:
- The design spec and plan are in
docs/superpowers/{specs,plans}/2026-09-29-settings-sidebar*. The user's uncommitted.gitignoreentry ignores them. - Onboarding is grouped under settings as "Getting started".
- Invitation pages use the settings frame without a sidebar link.
- The design spec and plan are in
- Verification:
npm run typecheckandgit diff --checkpassed.npm testpassed, 92 tests.- A fresh reviewer checked the whole change and found no correctness bugs. The fixes it prompted are in: a way home for signed-out visitors, the README, and the profile button's accessible name.
- Inspected desktop and mobile screenshots of the dashboard, profile menu, settings, help, privacy, 404, and the settings drawer.
npm run lintexits 1, but only because of 4 errors in the untrackedapp/web/src/app/LandingPage.tsx. Three arereact-hooks/set-state-in-effectand one isno-html-link-for-pages. That file is a user-added design export outside this task and was left untouched. Every file this task changed lints cleanly.
- Known issues:
LandingPage.tsxandRequirementsSidebar.tsxare untracked and unused.LandingPage.tsxblocks lint until it is fixed or removed.- Deferred review minors:
- The profile menu does not close on Escape or an outside click.
- The profile menu says "Log out" but the account page says "Sign out".
- The settings breadcrumb always reads "Settings".
- Stale
/accountcallback intests/schema/auth-email.spec.ts. - Leftover
.account-pageCSS.
- Exact next step: review the diff, resolve
LandingPage.tsxlint errors, then commit and push to the existing PR only after explicit user approval. Merge intomainthrough the pull request.
- Branch:
scaffolding; builds on commit765b3d1. Changes are uncommitted. - Completed: forgot-password, all reset-password states, and the sign-in error
page now use the same evidence-path layout and eyebrow label as login and
signup. The layout moved to
components/auth-layout.tsx. Error alerts use a newnotice-errorstyle. Previouslytext-red-600was overridden by.notice, so errors looked like status messages. Related-page link cards keep their neutral text color on public pages, and the public mobile menu closes after each route change. - Changed files:
app/web/src/components/{auth-layout,auth-form,password-forms,account-panel,main-navigation}.tsx,app/web/src/app/auth/error/page.tsx,app/web/src/app/public-pages.css,tests/e2e/auth.spec.ts, and this file. - Decisions and assumptions: recovery pages use the "Account recovery" label and the sign-in error page uses "Sign-in". No auth behavior changed.
- Verification:
npm run lint,npm run typecheck,git diff --check, and the fullnpm testsuite (83 passed) ran. Inspected the auth error desktop and forgot-password mobile screenshots. - Known limits: the landing page's mobile menu uses the same
<details>pattern and still stays open after its in-page "Product" link. - Exact next step: review the diff, then commit and push to the existing PR only
after explicit user approval. Merge into
mainthrough the pull request.
- Branch:
scaffolding; committed as765b3d1. - Completed: restyled shared placeholder routes, their related-page navigation, the About hub, account and error states, and public/auth layouts to match the dashboard and landing page's charcoal and lavender visual language. Login and signup now show the evidence path while retaining email/password, Google, and GitHub flows. Added responsive public navigation and kept planned routes explicitly labeled as disconnected previews.
- Changed files: shared web components and styles under
app/web/src/,tests/e2e/{home,scaffold}.spec.ts,docs/{TESTING,HANDOFF}.md, anddocs/landing-design/README.md. - Decisions and assumptions: use the existing dashboard and landing page as the visual reference (ADR-020). Keep the saved login/signup images as concepts; ADR-016's additional sign-in methods take precedence over their GitHub-only depiction. No product data, backend contract, or auth behavior changed.
- Verification:
npm run lint,npm run typecheck, andgit diff --checkpassed. The focused 19-test Chromium suite and the fullnpm testsuite passed (83 tests); the test setup built the web app and API. Inspected desktop screenshots for Teams and login and mobile screenshots for login, signup, and password reset. The full test run logged expected Better Auth rejection messages for negative tests. - Known limits: placeholder routes still have no connected data or actions; live OAuth and email delivery remain outside this visual task.
- Exact next step: review the uncommitted diff and screenshots, then commit and
push to the existing PR only after explicit user approval. Merge into
mainthrough the pull request.
- Branch:
scaffolding; merge oforigin/main(077b80d) is resolved locally and remains uncommitted. - Completed: combined the scaffold's
AppFrameand session redirects with the email, Google, and GitHub auth forms from main. Account navigation now opens/account. Preserved the local docstring review note below, reconciled the architecture summary, and assigned unique ADR numbers 015 through 020. - Changed files: merge updates across web auth, tests, and docs; manual conflict
resolutions in
app/web/src/app/layout.tsx,app/web/src/app/{login,signup}/page.tsx, anddocs/{ARCHITECTURE,HANDOFF}.md, plus account links,docs/DECISIONS.md, andtests/e2e/auth.spec.ts. - Decision: retain the scaffold's route structure and preview while adopting main's newer sign-in methods and account management.
- Verification:
npm run lint,npm run typecheck, andnpm testpassed (81 tests). The focused active-session navigation test passed after its account link assertion was added. The test runner logged a database disconnect during disposable database teardown after the tests passed. - Known limits: the resolution is local until committed and pushed. Deployment
still needs the email configuration described in
docs/DEPLOYMENT.md; live OAuth and email flows remain unverified here. - Exact next step: review the staged merge resolution, then commit and push it
only with explicit user approval; GitHub PR #7 requires the updated branch
before it can be merged into
mainthrough the PR.
- Branch:
scaffolding; CodeRabbit committed the docstring update asf898fef. - Completed: reviewed the generated JSDoc across 82 frontend files and synchronized the local branch with that commit. Route-page comments identify placeholders; shared-component and route-helper comments describe behavior and sample-data limits.
- Changed files: CodeRabbit changed frontend pages, shared components, and
app/web/src/lib/scaffold-routes.ts; this handoff is the only local edit. - Decision: keep the documentation update on the existing PR. It does not change runtime behavior.
- Verification:
npm run lint,npm run typecheck, andgit diff --check 3e0517e..HEADpassed locally. The PRverifyworkflow passed onf898fef. - Known limits: CodeRabbit's 0% pre-merge comment is stale because its next review was skipped pending manual review; the updated percentage is unverified. A separate CodeRabbit task for two review comments reported that its changes were ready but delivery needed attention; no second commit reached this branch.
- Exact next step: obtain a fresh CodeRabbit review for the docstring metric, inspect the separate task's delivery issue, and commit this handoff only with user approval.
- Branch:
scaffolding. - Completed: start the main product navigation test at
/dashboard, where the product sidebar containing the Teams link now appears. The public landing page has separate navigation. - Changed files:
tests/e2e/scaffold.spec.tsand this handoff. - Decision: preserve the distinct public and product navigation; the test now enters the product area before asserting its links.
- Verification:
npm run lintandnpm run typecheckpassed. The focused Playwright test passed (1 test), andnpm testpassed all 64 tests, including web and API test builds. The test runner printed a PostgreSQL disconnect warning during disposable database teardown after the tests passed. - Known limits: the CI run for this uncommitted fix has not been observed.
- Exact next step: review the diff, then commit and push the fix to the open pull request with explicit user approval for the commit.
- Branch:
scaffolding; follows public page design concepts. - Completed: implemented the simplified landing page based on
docs/landing-design/landing-v2.png, including the dark charcoal hero, lavender accent typography, interactive ST-104 evidence thread demo, dedicated landing navigation with session awareness and mobile menu, and quiet landing footer. Removed leftover v1 demo captions and aligned styling to the v2 concept. - Changed files:
app/web/src/app/page.tsx,app/web/src/app/landing.css,app/web/src/app/layout.tsx,app/web/src/components/app-frame.tsx,app/web/src/components/main-navigation.tsx,tests/e2e/home.spec.ts, and this handoff. - Decisions and assumptions: render
LandingNavigationand the quiet landing footer specifically whenpathname === "/"; keep the evidence demo deterministic without client-side mock churn; support narrow screens down to 390px using native<details>for mobile navigation. - Verification:
npm run typecheckandnpm run lintboth passed with 0 errors. Home and narrow-screen Playwright tests are defined intests/e2e/home.spec.ts(full browser test execution requires local Docker daemon for Better Auth test database). - Known limits: authentication pages (
/loginand/signup) remain on the previous scaffold and have not yet been updated to matchdocs/landing-design/{login-v2,signup-v2}.png. - Exact next step: review and approve changes, then decide whether to proceed with updating the
/loginand/signupauthentication pages.
- Branch:
scaffolding; no application code was changed. - Completed: revised all three public-page concepts with less visual weight and
saved the new versions next to the original images in
docs/landing-design/. - Changed files:
docs/landing-design/{landing-v2,login-v2,signup-v2}.png,docs/landing-design/README.md, and this handoff. - Decisions and assumptions: retain the dashboard's charcoal/lavender language, the requirement-to-review thread, and GitHub-only authentication. The revised set is the current proposal; the originals remain for comparison.
- Verification: visually inspected each generated image and checked its local file and README link. No app build or test was needed for image-only changes.
- Known limits: image-generated copy and icons need review during implementation; the concepts remain desktop-only and are not implemented pages.
- Exact next step: collect feedback on the simpler set before implementing responsive, accessible landing and authentication pages.
- Branch:
scaffolding; no application code was changed for this task. - Completed: generated matching landing, login, and signup visual concepts and
saved them with relative links in
docs/landing-design/for team review. - Changed files:
docs/landing-design/{README.md,landing.png,login.png,signup.png}and this handoff. - Decisions and assumptions: continue the dashboard's charcoal and lavender visual language; show an inspectable evidence path; preserve GitHub-only auth. The images are proposals, not accepted UI specifications.
- Verification: inspected each image for layout and product-language fit. The first landing draft had extra panels; its saved revision removes them. No app build or test was needed because this task changes only design artifacts.
- Known limits: image-generated text and icons need normal implementation review; the concepts are desktop views and do not define responsive layouts.
- Exact next step: get the team's feedback on these concepts, then implement the selected direction with responsive and accessible behavior.
- Branch:
scaffolding; this follows the browser icon correction. - Completed: the landing page and other public pages now show the existing SpecThread thread mark beside the brand name in the shared header.
- Changed files:
app/web/src/components/app-frame.tsx,app/web/src/app/globals.css,tests/e2e/home.spec.ts, and this handoff. - Decision: reuse the same image as the product sidebar and browser tab.
- Verification:
npm run lintandnpm run typecheckpassed. The focused Playwright home-to-dashboard browser test passed (1 test); its public-header image assertion and screenshot confirm that the mark loads. - Known limits: the landing page body is still the initial light scaffold and has not received a broader design pass.
- Exact next step: confirm whether the user wants a full landing page redesign; if so, treat it as a separate visual feature and retain the shared header.
- Branch:
scaffolding; this is a follow-up to the dashboard shell work. - Completed: removed the default Next.js/Vercel
favicon.icoand installed the existing SpecThread thread mark as the root App Routericon.png. - Changed files:
app/web/src/app/favicon.ico(removed),app/web/src/app/icon.png(added),tests/e2e/home.spec.ts, and this handoff. - Decision: reuse
app/web/public/thread-mark.pngso the browser tab and product sidebar show the same brand mark; no additional image dependency. - Verification:
npm run lintandnpm run typecheckpassed. The focused Playwright browser test passed (1 test), including the web and API test builds and an assertion that the page emits the new/icon.pngmetadata link. - Known limits: browsers may retain an old tab icon until they reload the page.
- Exact next step: continue the project and requirement data contract work;
merge branch changes through a pull request, not directly into
main.
- Branch:
scaffolding; the shell is committed as9b7f652and the dashboard preview asa68e465. The QA artifacts and documentation are in a separate follow-up commit. - Completed: replaced the dashboard cards with the approved compact work list and inline evidence path. Product routes now share a persistent dark sidebar and route header; public pages retain their existing header and footer. Dashboard tabs, row expansion, group collapse, sorting, filtering, quick navigation, mobile drawer, and links to existing example routes work. Sample requirements and the example team are explicitly labeled as preview content.
- Changed files:
app/web/src/{app/{layout,globals.css,app-shell.css,dashboard/page.tsx},components/{app-frame,dashboard-preview}.tsx},app/web/public/thread-mark.png,app/web/package.json,package-lock.json,tests/e2e/{home,scaffold,auth}.spec.ts,docs/assets/thread-mark-source.png,docs/dashboard-qa/(the QA report and three image artifacts),scripts/process-thread-mark.py, anddocs/{ARCHITECTURE,DECISIONS,TESTING,HANDOFF}.md. - Decisions: ADR-020 records the shared shell and public sample preview. Added
lucide-reactbecause the web app had no reusable icon set; no API, schema, session, or authorization behavior changed. The transparent brand mark is produced fromdocs/assets/thread-mark-source.pngwithpython scripts/process-thread-mark.py(requires Pillow). - Verification: browser inspection covered desktop and 390px mobile layouts,
evidence expansion, tabs, and a route transition.
npm testpassed 63 tests, including the web and API builds. The focused dashboard suite passed 8 tests after the tab refinement and console-error assertion; the final screenshot test passed after the logo update.npm run lint,npm run typecheck, and standalonenpm run buildpassed on the final code. Asset regeneration passed.git diff --checkand the final diff review passed. The design QA report and its source, implementation, and comparison images are stored together indocs/dashboard-qa/with relative links. - Known limits: dashboard rows and team navigation are examples, not account data. Project authorization and real requirement APIs are still pending. The current product routes remain public and must be protected before showing private data.
- Exact next step: define the authorized project and requirement read contract, then replace the preview rows and example team with real accessible data. Do request explicit approval for future commits; merge through a pull request only.
- Branch:
scaffolding, continuing the user's routing work. Changes remain uncommitted; no CSS or backend product endpoint was changed. - Completed: added one route catalog and shared navigation to the dashboard and all placeholder pages. Parent, child, and related links connect Teams, personal/team Projects, Requirements, Evidence, Review, account Settings, onboarding, help, invitations, and optional routes. Links needing unknown IDs are explicitly marked as example routes. Added a Settings landing page and made the dashboard's Create project and Connect GitHub controls link to their placeholder routes. The main header now links to Notifications and Settings and shows Account instead of Log in/Sign up for an active client session.
- Auth behavior: login and signup use Better Auth's server-validated session to
redirect an already signed-in user to
/dashboard. The existing GitHub OAuth callback already targets/dashboard; no raw browser token is trusted for the redirect. The dashboard remains a public empty preview. - Changed files:
app/web/src/{lib/scaffold-routes.ts,components/{scaffold-navigation,main-navigation,scaffold-page}.tsx,app/{layout,dashboard/page,login/page,signup/page,settings/page}.tsx};playwright.config.ts;tests/e2e/{auth,home,scaffold}.spec.ts;docs/{ARCHITECTURE,DECISIONS,TESTING,HANDOFF}.md. - Decision: ADR-019 records navigation and session redirect semantics. A per-run random test secret is shared across Playwright workers so the disposable session test uses the same secret as the test web server.
- Verification:
npm run lintandnpm run typecheckpassed. Finalnpm testpassed 61 tests and built the web and API applications. The browser tests cover the main route journey, active and invalid sessions, and registration of all reserved pages in navigation.git diff --checkpassed. - Known risks: pages remain public placeholders without project membership checks or real entity links. Example IDs exist only to exercise the route structure. Real GitHub OAuth, deployed session behavior, and product data navigation were not verified in this task.
- Exact next step: implement a real project list and authorization contract,
then replace example links with IDs from accessible projects. Do not commit
without explicit user approval; merge to
mainonly through a pull request.
- Branch:
scaffolding, continuing the route task on the user-selected branch. Changes are uncommitted. - Completed: removed the speculative standalone
/searchpage. Added/aboutas an informational hub and moved How it works, Privacy, and Terms to/about/how-it-works,/about/privacy, and/about/terms; linked the hub in the footer. Clarified that/projectscovers both personal and team-owned projects, while/teams/[teamId]/projectsis the team subset. Project creation and ownership placeholders now mention both ownership choices. - Changed files:
app/web/src/app/about/, removed top-level information and searchpage.tsxfiles, updated project placeholder pages and root layout,tests/e2e/scaffold.spec.ts, anddocs/{PROJECT,DECISIONS,TESTING,HANDOFF}.md. - Decision: ADR-018 records the route hierarchy. The user selected the About hub with separate child URLs. Search remains a possible control within list pages, with no global search route. No data-model or API contract was changed.
- Verification:
npm run lintandnpm run typecheckpassed.npm testpassed all 57 tests and built the web and API applications.git diff --checkpassed. - Known risk: information and product pages remain placeholders. Team membership, authorization, personal/team ownership, and transfer behavior still need backend decisions and implementation. Old top-level information URLs now return 404; they were only scaffold pages and had no navigation links.
- Exact next step: define the first real project flow and its access rules,
then replace the relevant placeholders. Do not commit without the user's
explicit approval; merge to
mainonly through a pull request.
- Branch:
scaffolding, created frommain. Changes are uncommitted. The pre-existing modifications topackage.json,package-lock.json, andskills-lock.jsonwere preserved and are outside this task. - Completed: added 68 bare frontend pages from the route blueprint covering public help, onboarding, teams, projects, requirements, evidence, review, invitations, account settings, and optional future views. Each uses one shared placeholder that clearly says product data and actions are not connected. Added Teams, Projects, and Reviews header links plus root error and not-found fallbacks. Existing home, auth, and dashboard screens remain.
- Changed files:
app/web/src/app/layout.tsx, 68 new routepage.tsxfiles inapp/web/src/app/,app/web/src/app/{error,not-found}.tsx,app/web/src/components/scaffold-page.tsx,tests/e2e/scaffold.spec.ts,docs/{TESTING,HANDOFF}.md. - Decisions and assumptions: route paths reserve navigation only and are not API or data-model contracts. A team-owned project is a proposed product direction; team ownership, membership, invitations, review permissions, and authorization remain undecided. Dynamic placeholder routes intentionally show no real entity data and do not validate IDs yet. No new dependencies, database changes, or backend endpoints were added.
- Verification:
npm run lintandnpm run typecheckpassed.npm run buildpassed with network access for the existing Google Fonts imports. Focused scaffold Playwright tests passed (2 tests before the 404 test was added), and the final fullnpm testpassed (54 tests, including all 3 scaffold tests). Final lint and typecheck passed after the last code edit;git diff --checkpassed. Docker Desktop was started for the disposable test database. - Known risks: all new pages are publicly reachable placeholders. They must gain real session and project authorization checks before showing product data. Later feature routes should be removed if the team rejects them.
- Exact next step: choose the first vertical slice and settle team ownership
and review permissions before connecting these pages to product data. Keep
this branch uncommitted until the user approves a commit; use a pull request
for any merge into
main.
- Branch: feature/email-google-auth (from main). Committed and opened as a PR. Nothing deployed; no database schema changes.
- Independent of the open feature/api-jwt-validation PR, which uses ADR-015. This task uses ADR-016.
- Restored app/web/.env.example from main to document the new variables. The app/api/.env.example working-tree deletion was left untouched.
- Completed:
- Better Auth email/password sign-in: verification required, 12-character minimum, verify links sign in, single-use reset links that revoke sessions.
- Google sign-in, enabled only when configured. GitHub sign-in kept.
/accountshows the profile and lets users link or unlink Google and GitHub, and sign out.- Unlinking must leave a usable method, meaning email/password or a provider enabled in this deployment. Enforced both in the UI and by a server hook on
/unlink-account(PR review follow-up). - New
/forgot-passwordand/reset-passwordpages; login and signup forms; fixed linking error messages; an Account nav link. - Email is sent through Resend with
fetch, or logged on loopback only withEMAIL_DELIVERY=log.
- Changed files:
- Web library: app/web/src/lib/{auth-config.ts,create-auth.ts,email.ts}
- Web components: app/web/src/components/{auth-form.tsx,password-forms.tsx,account-panel.tsx}; auth-placeholder.tsx removed
- Web pages: app/web/src/app/{login,signup,forgot-password,reset-password,account,auth/error}/page.tsx, layout.tsx, globals.css
- Config: app/web/.env.example, playwright.config.ts
- Tests: tests/api/auth-config.spec.ts, tests/e2e/{auth,home}.spec.ts, tests/schema/{auth-email,auth-runtime}.spec.ts
- Docs: README.md, docs/{ARCHITECTURE,DECISIONS,DEPLOYMENT,TESTING,HANDOFF}.md
- Decisions: ADR-016.
- Implicit linking by email keeps Better Auth's default: both the provider and the local account must have verified the email.
- Explicit linking allows a GitHub or Google email that differs from the account email.
- Duplicate sign-up and reset requests give the same response, so they don't reveal which emails exist.
- No migration was needed; the existing tables cover it.
- Verification:
npm run lint: passed.npm run typecheck: passed.npm test: 48 passed, including 5 new schema flow tests, 7 new browser tests and 2 new config tests.npm run build: passes withEMAIL_DELIVERY=log. It fails explicitly without Resend settings, as designed.git diff --check: passed.- Manual: a real Resend verification email from mail.spec-thread.com was received locally. The web app pointed at the shared Supabase database during this test, so test sign-ups exist there.
- Known issues or risks:
- Vercel deploys now fail until
RESEND_API_KEYandEMAIL_FROMare set. Google needsGOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRET. - Local
.env.localneedsEMAIL_DELIVERY=log, or Resend settings. - The team GitHub App is private, so non-owners get a 404 until it is made public (DEPLOYMENT.md).
- Not automated, so still to be verified manually: real Google and GitHub linking callbacks, implicit linking, and Resend delivery.
- Unlinking requires a recent sign-in (Better Auth's fresh-session rule).
- After sign-in, users still land on the public dashboard preview.
- Vercel deploys now fail until
- Exact next step:
- Before merging, a teammate with Vercel access sets
RESEND_API_KEY,EMAIL_FROM(sender on mail.spec-thread.com) and, optionally, the Google credentials, and makes the GitHub App public. - Still to verify manually: verify link then password login, password reset, linking GitHub or Google from
/account, and Google sign-in.
- Before merging, a teammate with Vercel access sets
- Branch: feature/api-jwt-validation, merged into main through PR #5 (840ed6a). Nothing was deployed and no Supabase changes were made.
- better-auth stays pinned to exactly 1.7.5. A commit loosening it to ^1.7.5 (fe77b92) was reverted in 7188a73, because the key-selection behavior behind the rollout was verified only against 1.7.5.
- Deleted app/web/.env.example and app/api/.env.example remain uncommitted in the working tree. They predate this task and are not part of it.
- Completed:
- Better Auth now signs JWTs with ES256 (
app/web/src/lib/create-auth.ts). - The API validates
Authorization: Bearertokens against{Auth:Issuer}/api/auth/jwks(app/api/Auth/). - Every endpoint requires authentication by default.
/healthand development OpenAPI stay anonymous. - New
GET /meendpoint returns{ "userId": sub }.
- Better Auth now signs JWTs with ES256 (
- Changed files:
- API: app/api/{Program.cs,SpecThread.Api.csproj,packages.lock.json}, app/api/Auth/{AuthenticationSetup.cs,JwksRetriever.cs}
- Web: app/web/src/lib/create-auth.ts
- Tests: scripts/start-test-jwks.mjs, playwright.config.ts, tests/api/{auth-jwt,auth-unconfigured,health}.spec.ts, tests/schema/auth-jwt-runtime.spec.ts, tests/support/api-process.ts
- Config and docs: render.yaml, README.md, docs/{ARCHITECTURE,DECISIONS,DEPLOYMENT,TESTING,HANDOFF}.md
- Decisions: ADR-015.
- ES256 instead of EdDSA, because .NET can't validate EdDSA without an extra library.
- Public keys come from the JWKS endpoint over HTTP, not from the jwks table.
- Endpoints are authenticated by default. Anonymous callers now get 401 on unknown routes instead of 404; this changed the existing health.spec test.
/meis a proposed contract, and the team may rename it.- Local manual testing needs its own database and GitHub OAuth app: the shared Supabase jwks table still holds EdDSA keys, and the team's GitHub App is private (other GitHub users get a 404 at authorize).
- Verification:
npm run lint,npm run typecheck, andnpm run build:apiall passed (0 warnings).npm test: 48 passed. Docker Desktop had to be started, and Playwright Chromium and dotnet tools had to be installed or restored locally first.git diff --checkpassed.- Manual check: local web app on a Docker Postgres with a personal GitHub OAuth app. A real ES256 token returned 200 from
GET /mewith the matching user id; the request without a token returned 401.
- Known issues or risks:
- Production needs the ordered rollout in DEPLOYMENT.md: deploy the web change, expire the EdDSA keys, then set
Auth__Issueron Render. - The API's key refresh depends on the web app's availability.
- No web code sends tokens to the API yet.
- Project membership checks are not implemented.
- Production needs the ordered rollout in DEPLOYMENT.md: deploy the web change, expire the EdDSA keys, then set
- Exact next step: carry out the ordered rollout in DEPLOYMENT.md (deploy the web change, expire the EdDSA keys, then set
Auth__Issueron Render). After that, implement project membership authorization.- Team follow-ups:
- Make the GitHub App public if non-owners will sign in on Vercel.
- Consider trimming the JWT payload to the user id with Better Auth's
definePayload. By default the token carries name, email, and avatar URL.
- Team follow-ups:
- Branch: auth/optimize, explicitly selected; already checked out at task start. Changes grouped into user-authorized skills, test harness, and auth commits. No production deployment, live migration, credential rotation, or existing OAuth-token rewrite was performed.
- Completed: used better-auth-best-practices and better-auth-security-best-practices, verifying examples against installed 1.7.5 code/types and Context7. Added early PEM parsing (including certificate bundles), trimmed/paired GitHub credentials, and built-in encryption of newly written OAuth tokens. Removed the unused public URL from the env example. Preserved the existing joins, rate limits, error page, exact trusted origins, and verified TLS.
- Changed files: app/web/.env.example, app/web/src/lib/{auth-config,create-auth}.ts, tests/api/auth-config.spec.ts, tests/schema/auth-runtime.spec.ts, playwright.config.ts, scripts/start-test-web.mjs, docs/{ARCHITECTURE,DECISIONS,DEPLOYMENT,TESTING,HANDOFF}.md.
- Verification exposed an existing harness defect: globalSetup runs after the webServer entries, so building there tried to overwrite the running API DLL. The first webServer entry now builds the API before the API entry starts.
- Checks: npm run lint and npm run typecheck passed. Focused auth-runtime schema tests passed 6/6. Final npm test passed 37/37 in 32.0s, with production web and Release API builds. git diff --check passed. Current local env passed config validation without printing values. Initial token retrieval tests were corrected to use 1.7.5's internal account row ID, without providerId, in the HTTP request.
- Decision: ADR-015; no new dependencies, environment variables, or migrations. Encryption does not backfill historical plaintext. Keep the existing secret and encryption option once ciphertext has been written. Prefixed legacy GitHub tokens are tested; hex-only legacy tokens may need reauthentication.
- Unverified: real OAuth against GitHub and deployed proxy behavior for this branch; no live Supabase database was touched. Prior handoff deployment/migration claims are historical, not independently reverified here. The existing AuthRateLimits migration is still a deployment prerequisite.
- User-added canonical .agents/skills files and skills-lock.json are included in the skills commit without content changes. .claude/skills and skills are local Windows junction aliases to those files and remain untracked, avoiding duplicate copies in Git.
- Exact next step: push auth/optimize and open a PR when requested. Merge into main only through the PR. Before deployment, verify AuthRateLimits is applied, retain BETTER_AUTH_SECRET, and recheck live GitHub sign-in/cancellation using DEPLOYMENT.md.
- Branch: main (explicitly authorized one-time exception for establishing repository governance).
- Completed:
- Updated
AGENTS.mdanddocs/WORKFLOW.mdestablishing mandatory agent branching instructions:- Never edit or commit directly on
main. - Detect
mainand immediately warn the user and prompt for a task branch name before making any changes. - On task branches, distinguish prompt iterations on the current task (stay on branch) from starting a different task (ask whether to stay or create a new branch).
- Mandatory Pull Requests for merging all code into
main.
- Never edit or commit directly on
- Added
.github/workflows/enforce-pr.ymlCI workflow that validates any push tomainoriginated from an associated, merged Pull Request (with[skip-pr-check]bypass flag for authorized emergency/setup commits).
- Updated
- Changed files:
AGENTS.md,docs/WORKFLOW.md,.github/workflows/enforce-pr.yml,docs/HANDOFF.md. - Verification:
npm run lintandnpm run typecheckpassed cleanly;git diff --checkpassed. - Exact next step: User commits and pushes this configuration to
main, and configures GitHub branch protection rules in repository settings to require Pull Requests.
- Branch: main, explicitly selected. Changes remain uncommitted; no live deployment or Supabase migration performed.
- Completed:
- Added public
/auth/errorpage (app/web/src/app/auth/error/page.tsx) rendering safe, sanitized error descriptions distinguishing user cancellation (access_denied), expired OAuth state (state_not_found/state_mismatch), and generic provider errors, with links to retry sign-in or return home. - Added
onAPIError: { errorURL: "/auth/error" }in Better Auth configuration anderrorCallbackURL: "/auth/error"when initiating social sign-in. - Updated
AuthPlaceholder(app/web/src/components/auth-placeholder.tsx) to handle returned Better Auth errors (including HTTP 429 throttling and network errors) and preserve loading state during redirection. - Set
appName: "SpecThread"in Better Auth server configuration. - Enabled Kysely PostgreSQL adapter
joins: trueand added session join integrity, expired/revoked session checks, and timing benchmark attachments to schema test reports. - Added shared rate-limiting storage via EF Core: added
AuthRateLimitmodel toapp/api/Data/AuthModels.csandSpecThreadDbContext.cs, scaffolded migration20260921021458_AuthRateLimitswith Row-Level Security (RLS) enabled and anon/authenticated permissions revoked, and generated idempotent forward/rollback SQL scripts (docs/schema/auth-rate-limits.sqlandauth-rate-limits-rollback.sql). - Added test database automation (
scripts/test-database.mjs,scripts/start-test-web.mjs, andscripts/stop-test-web-database.mjs) supporting ephemeral Docker PostgreSQL testing for web and schema suites, resilient against UTF-8 BOMs in SQL migration files. - Resolved CodeRabbit review feedback: added
scripts/build-api.mjsviaglobalSetupinplaywright.config.tsto build the API before server startup (preventing race conditions with concurrent webServer launchers), invoked compiled API DLL directly to prevent wrapper process leaks on Windows, and moved cache file operations inside thetryblock inscripts/start-test-web.mjsto protect database container cleanup. - Added comprehensive Playwright tests in
tests/e2e/auth.spec.ts(covering error page, retryable initiation, network failure, 429 throttling, accessibility, and narrow screen layout) andtests/schema/auth-runtime.spec.ts(covering rate-limit schema match, RLS enforcement, multi-instance rate limiting, OAuth cancellation, session joins, and rollback/reapply).
- Added public
- Changed files:
app/api/Data/AuthModels.cs,app/api/Data/SpecThreadDbContext.cs,app/api/Migrations/SpecThreadDbContextModelSnapshot.csapp/api/Migrations/20260921021458_AuthRateLimits.cs,app/api/Migrations/20260921021458_AuthRateLimits.Designer.csapp/web/src/lib/create-auth.ts,app/web/src/lib/auth.ts,app/web/src/lib/auth-client.ts,app/web/src/components/auth-placeholder.tsx,app/web/src/app/auth/error/page.tsxdocs/schema/auth-rate-limits.sql,docs/schema/auth-rate-limits-rollback.sqlscripts/generate-auth-rate-limits.mjs,scripts/start-test-web.mjs,scripts/stop-test-web-database.mjs,scripts/test-database.d.mts,scripts/test-database.mjsplaywright.config.ts,tests/e2e/auth.spec.ts,tests/schema/auth-runtime.spec.ts,tests/schema/migration.spec.tsdocs/DATABASE.md,docs/DECISIONS.md(ADR-014),docs/DEPLOYMENT.md,docs/TESTING.md,docs/HANDOFF.md
- Decisions: ADR-014. Name auth app SpecThread, enable joins, use PostgreSQL shared rate-limiting storage via EF Core migration. Retain production-only rate limiting defaults. Error page is public and database-independent. Browser auth requests use the current origin.
- Verification:
npm run lint: passed cleanly.npm run typecheck: passed cleanly across Next.js and root workspaces.dotnet build app/api --configuration Release: passed with 0 warnings, 0 errors.npx playwright test --project=api: 11 passed in 36.0s.npx playwright test --project=chromium: 12 passed in 26.0s.npx playwright test --project=schema: 11 passed in 34.1s.npm test: all 34 tests across 7 files passed in 37.2s.git diff --check: passed.
- Known issues or risks:
- Live Supabase database must have the
AuthRateLimitsmigration applied (dotnet ef database update AuthRateLimits --project app/apior viadocs/schema/auth-rate-limits.sql) before deploying the updated web application; database outages will affect auth requests subject to rate limiting. - GitHub-side misconfigurations (e.g., unregistered redirect URI) display error messages directly on GitHub and cannot return to the local
/auth/errorpage. - Real GitHub login and cancellation on live Vercel deployment must be verified following the rollout steps in
docs/DEPLOYMENT.md.
- Live Supabase database must have the
- Exact next step:
- Obtain user approval to commit these uncommitted changes to
main. - Apply
AuthRateLimitsmigration to Supabase. - Deploy updated web app to Vercel and verify live GitHub sign-in, cancellation, and error handling.
- Obtain user approval to commit these uncommitted changes to
- Branch: main, explicitly selected. Recommendation 1 only; no commit or deployment.
- Completed: Better Auth now prefers x-vercel-forwarded-for, with x-forwarded-for as fallback. Added HTTP-handler tests for header precedence, distinct client buckets, 429 responses, fallback from absent/invalid Vercel headers, and ignoring unrelated Cloudflare headers. Tests use isolated in-memory limits, no live data.
- Changed files: app/web/src/lib/{auth.ts,auth-config.ts}, tests/api/auth-config.spec.ts, docs/{DEPLOYMENT,DECISIONS,HANDOFF}.md.
- Decision: ADR-013. Trust assumes Vercel-managed ingress. Existing rate-limit defaults and in-memory storage are unchanged; distributed storage is deferred.
- Verification: npm run lint and npm run typecheck passed; npm test -- --project=api --project=chromium passed all 17 tests, including managed production web and Release API builds. git diff --check passed. The sandbox initially blocked process spawning (EPERM); the approved retry ran. First test run had one assertion failure: this Better Auth version uses X-Retry-After, not Retry-After. Corrected the assertion and reran successfully.
- Unverified: deployed proxy header handling and distributed rate limiting. Docker schema tests were not run; this task changes no database schema.
- Prior login follow-up: corrected the ignored local CA environment formatting; the user subsequently confirmed GitHub login both locally and on Vercel.
- Exact next step: review these uncommitted changes and verify header behavior in a controlled Vercel deployment. Wait for the user's confirmation before starting recommendation 2. OAuth error pages, joins, and app naming remain unchanged.
- Branch: main, explicitly selected. Changes remain uncommitted; no deployment, production environment edits, key rotation, or database migration performed.
- Completed: removed hardcoded dashboard key and default secret fallback; required explicit secret/base URL/database settings; restricted trusted origins to the canonical app origin; enforced certificate verification for remote pg connections with optional DATABASE_CA_CERT PEM; made dashboard plugin opt-in.
- Playwright web server uses isolated credentials and an unreachable loopback database, with GitHub and dashboard integrations disabled. Added config failure, TLS-override, and HTTP origin rejection/acceptance tests.
- Changed files: app/web/src/lib/{auth.ts,auth-config.ts}, app/web/.env.example, playwright.config.ts, tests/api/auth-config.spec.ts, tests/e2e/home.spec.ts, README.md, docs/{ARCHITECTURE,DATABASE,DECISIONS,DEPLOYMENT,TESTING,HANDOFF}.md.
- Decisions: ADR-012; no new dependencies or changes to EF ownership. Public RLS tables remain unchanged. Corrected stale docs and the claim that migration SQL is idempotent. Historical handoff below describes earlier work, not current scope.
- Checks: npm run lint and npm run typecheck passed. Latest npm test built the production web and Release API successfully; all 15 non-schema tests passed. Schema setup failed because Docker's dockerDesktopLinuxEngine pipe was absent, leaving five further schema tests skipped. Launching Docker Desktop hidden and checking docker info did not restore the engine. No schema code was changed. Initial origin test was corrected to use a cookie-bearing sign-out request. git diff --check passed. C# sources were unchanged.
- Unverified: full schema suite in this session, real GitHub OAuth, and deployed TLS connectivity. Existing handoff deployment/migration reports were not independently revalidated. No production credentials were printed.
- Exact next steps: restore Docker engine and rerun npm test; rotate the previously committed Better Auth dashboard key; configure Vercel's required secret, exact URL, database URL, and CA PEM before deployment. If the old default auth secret was used, replace it too (existing sessions may need sign-in). Follow DEPLOYMENT.md. Obtain explicit approval before committing. C# JWT validation and project authorization remain separate unfinished tasks.
- Branch: main, continuing on approved integration branch.
- Live Deployments:
- Web (Vercel): https://web-alpha-lovat-61.vercel.app/
- API (Render): https://specthread-api.onrender.com/
- Completed work:
- Added .dockerignore ignoring host build artifacts (bin/, obj/), .git, .next, node_modules, and local env files for fast, clean container builds.
- Created root multi-stage Dockerfile targeting official Microsoft .NET 10 SDK and ASP.NET runtime images, restoring in locked mode and running unprivileged as $APP_UID on port 8080.
- Solved Supabase Root CA validation for production containers: added app/api/certs/prod-ca-2021.crt and configured the Dockerfile runtime stage to install it via update-ca-certificates into the Debian trust store (/etc/ssl/certs/ca-certificates.crt).
- Verified Docker container build and certificate trust via openssl verify; Npgsql connects with SSL Mode=VerifyFull without requiring local file path parameters in Render environment variables.
- Created render.yaml defining the Render Blueprint web service specification for specthread-api.
- Added app/web/vercel.json and installed typescript in app/web devDependencies for clean isolated Vercel builds.
- Added https://*.vercel.app to Better Auth trustedOrigins in app/web/src/lib/auth.ts for seamless cross-origin and preview authentication.
- Authored comprehensive docs/DEPLOYMENT.md guide covering Vercel and Render step-by-step setup, environment variables, GitHub OAuth callback URLs, TLS certificate configuration, and verification.
- Recorded ADR-010 and ADR-011 in docs/DECISIONS.md and updated docs/ARCHITECTURE.md.
- Changed files:
- .dockerignore, Dockerfile, render.yaml, app/web/vercel.json, app/web/package.json, package-lock.json
- app/web/src/lib/auth.ts, app/api/certs/prod-ca-2021.crt, docs/DEPLOYMENT.md, docs/DECISIONS.md, docs/ARCHITECTURE.md, docs/HANDOFF.md
- Validation:
- Live Render API: GET https://specthread-api.onrender.com/health returned 200 OK ({"status":"ok"}).
- Live Vercel Web: GET https://web-alpha-lovat-61.vercel.app/ returned 200 OK with SpecThread landing page.
- Live Better Auth: GET https://web-alpha-lovat-61.vercel.app/api/auth/get-session returned 200 OK (null for unauthenticated).
- docker build: passed in 7.1s, 701B context transfer.
- docker container cert verification: openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt /usr/local/share/ca-certificates/supabase-root-2021.crt returned OK.
- npm run lint: passed cleanly.
- npm run typecheck: passed cleanly.
- npm run build: Next.js production build succeeded in 1.1s.
- dotnet build app/api --configuration Release: passed with 0 warnings, 0 errors.
- npx playwright test: 17 passed in 31.2s.
- git diff --check: passed.
- Known issues or risks:
- GitHub OAuth Application must have Homepage URL and Authorization callback URL configured to the live Vercel domain.
- Exact next step:
- Update GitHub OAuth App Authorization callback URL to https://web-alpha-lovat-61.vercel.app/api/auth/callback/github, set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET on Vercel, and test live GitHub authentication.
- Branch: main, continuing the approved sequence.
- Completed work:
- Finalized C# EF Core models in app/api/Data/{AuthModels.cs, ProductModels.cs, SpecThreadDbContext.cs}.
- Generated and finalized EF Core migration 20260919042809_InitialSchema with embedded PostgreSQL Row-Level Security (RLS) and public/anon/authenticated role privilege revocation.
- Generated idempotent DDL artifacts docs/schema/initial.sql and docs/schema/rollback.sql.
- Executed dotnet ef database update applying the migration to the live Supabase PostgreSQL database via the session pooler; all 9 tables, indices, check constraints, foreign keys, and RLS policies are live.
- Verified EF model snapshot matching and tested schema integrity, Better Auth compatibility, constraints, and rollback in an ephemeral Docker container.
- Implemented Better Auth in app/web: installed better-auth: 1.7.5 and pg: 8.23.0 with @types/pg: 8.23.1, added app/web/src/lib/auth.ts (PostgreSQL adapter, JWT plugin, GitHub social provider, validateSchema: false), app/web/src/lib/auth-client.ts (jwtClient), and app/web/src/app/api/auth/[...all]/route.ts (toNextJsHandler).
- Documented environment variables in app/web/.env.example.
- Updated app/web/src/components/auth-placeholder.tsx to provide an interactive GitHub sign-in button with loading and error states.
- Updated tests/e2e/home.spec.ts with checks for interactive GitHub buttons and Better Auth /api/auth/get-session endpoint response.
- Recorded ADR-009 in docs/DECISIONS.md.
- Changed files:
- app/api/Data/SpecThreadDbContext.cs, app/api/Data/AuthModels.cs, app/api/Data/ProductModels.cs
- app/api/Migrations/20260919042809_InitialSchema.cs, .Designer.cs, SpecThreadDbContextModelSnapshot.cs
- docs/schema/initial.sql, rollback.sql, better-auth-1.7.5.json
- scripts/generate-initial-schema.mjs, package.json, app/web/package.json
- app/web/src/lib/auth.ts, auth-client.ts, app/web/src/app/api/auth/[...all]/route.ts, app/web/src/components/auth-placeholder.tsx, app/web/.env.example
- playwright.config.ts, tests/schema/migration.spec.ts, tests/api/ef.spec.ts, tests/e2e/home.spec.ts
- docs/DECISIONS.md, docs/HANDOFF.md
- Validation:
- npm run lint: passed cleanly with zero errors.
- npm run typecheck: passed cleanly across Next.js and root workspaces.
- npm run build: production Next.js build succeeded in 2.4s.
- dotnet build app/api --configuration Release: passed with 0 warnings, 0 errors.
- dotnet ef database update --project app/api: succeeded on Supabase; applied 20260919042809_InitialSchema.
- dotnet ef migrations list --project app/api: verified no pending migrations on Supabase.
- npx playwright test: 17 passed across Chromium, API, and Schema suites in 29.3s.
- Known issues or risks:
- Live GitHub sign-in requires GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET configured in the runtime environment.
- Next.js web application requires DATABASE_URL and BETTER_AUTH_SECRET configured for live session persistence.
- Exact next step:
- Create the GitHub OAuth application (or GitHub App), configure the credentials in app/web/.env.local, and test live sign-in flow and JWT verification against the ASP.NET Core API.
- Branch: main, explicitly authorized. Existing connection-check handoff edits preserved.
- Added a homepage, login, signup, and empty public dashboard preview with shared navigation, responsive styling, page titles, and a keyboard skip link.
- GitHub sign-in and create/connect actions are visibly unavailable and disabled. No credential collection, fake sessions, API changes, data writes, or dependencies.
- Updated files: app/web/src/app/{page.tsx,layout.tsx,globals.css}; added login/page.tsx, signup/page.tsx, dashboard/page.tsx, and app/web/src/components/auth-placeholder.tsx. Updated tests/e2e/home.spec.ts, README.md, TESTING.md, ARCHITECTURE.md, DECISIONS.md, and this handoff.
- Recorded the user's approved Better Auth/GitHub OAuth, GitHub Apps, and project membership direction in ADR-008. Implementation is explicitly deferred.
- Validation: npm run lint and npm run typecheck passed. npm test passed all nine tests in 19.7 seconds, including web production and API builds. Initial build failed on a CSS UTF-8 BOM; removing the BOM resolved it. git diff --check passed. Reviewed desktop home and mobile login/dashboard screenshots under test-results/; no overflow or obscured controls. React review: server components, semantic links and headings, visible focus, no unnecessary hooks or client state.
- Unverified: real authentication, authorization, persistence, and GitHub actions remain intentionally unimplemented; no deployment was attempted.
- Limits: dashboard is public only because it has no real data; authentication and project authorization must be enforced before real product data is exposed.
- Exact next step: wait for the user's instruction to create tables, then implement Better Auth and GitHub integrations in the requested order. Deployment is deferred. No commits or pushes made for this UI task.
- Task: establish the approved Next.js/.NET/Supabase foundation.
- Branch:
main, explicitly requested by the user. No branch created, commits made, or pushes performed for this task. - Web: existing Next.js 16.3.5 application moved to
app/webwith source and assets preserved byte-for-byte according to Git blob hashes. - API: ASP.NET Core 10 in
app/api, SDK 10.0.401, nullable checks and warnings as errors.GET /healthreturns{ "status": "ok" }; development exposes/openapi/v1.json. - Database: Supabase PostgreSQL, with EF Core 10 and Npgsql initialized as the sole ORM/migration system. Drizzle was explicitly replaced with user approval.
- EF context has no entities or migrations. Startup and health checks never query or modify a database. No live Supabase database query or migration was executed.
- Supabase MCP is configured globally for project
hgcjtecsglksdbsmtcxtand authenticated.codex mcp loginsucceeded;codex mcp listreports enabled/OAuth. - Pending branch-permission edits in AGENTS.md and WORKFLOW.md were preserved. Ask permission before each new task branch; remain on the current branch when chosen, and retain that choice throughout follow-up work.
- Moved
src/,public/,next.config.ts,postcss.config.mjs, and the web TypeScript configuration intoapp/web; added its package manifest and env example. Root package.json and package-lock.json now define a single npm workspace. - Added
app/api/Program.cs,Data/SpecThreadDbContext.cs, project file, generated NuGet lockfile, and placeholder-only environment example. - Added
global.jsonand generateddotnet-tools.jsonwith dotnet-ef 10.0.12. - Updated root TypeScript, ESLint, Git ignore, npm scripts, and Playwright config.
- Added HTTP health/OpenAPI/404 tests and EF initialization/missing-config tests
under
tests/api/; retained the existing Chromium homepage smoke test. - Added
.github/workflows/ci.ymlusing the documented local checks. - Renamed
docs/PROJECTS.mdtodocs/PROJECT.mdto match existing references. - Updated README, AGENTS.md, ARCHITECTURE.md, WORKFLOW.md, TESTING.md, and DECISIONS.md (ADR-006/007). Added DATABASE.md and refreshed this handoff.
- Optional duplicate Supabase skills installation skipped: the Supabase skill is already installed. No application dependency on the Supabase client SDK.
- Approved layout is singular
app/webandapp/api. - Node.js 24/npm 11; existing web dependency versions retained. One npm lockfile.
- EF and OpenAPI packages are 10.0.12; Npgsql EF provider is 10.0.3. Versions were checked against NuGet; the generated lockfile pins transitive dependencies.
- New API dependencies provide OpenAPI, PostgreSQL EF access, and design-time migration tooling. No product models, authentication, or repository integrations.
- EF must be initialized before database execution. No automatic startup migration or database creation. Supabase-managed schemas remain outside application ownership.
- Docker Compose deferred because no current check needs a database.
- Authentication, API deployment provider, GitHub App/OAuth choice, first feature contract/schema, and team merge policy still need agreement.
npm install: passed; regenerated workspace lockfile.npm ci: passed; 368 packages installed, audit reported 0 vulnerabilities.dotnet restore app/api --locked-mode: passed.dotnet tool restore: passed, dotnet-ef 10.0.12 restored.dotnet build app/api --configuration Release --no-restore: passed, zero warnings and errors.dotnet format app/api --verify-no-changes --no-restore: passed.- Initial
npm run lintandnpm run typecheck: passed after the move. - Initial
npm test: 4 passed (homepage and three HTTP API checks), including web production build and managed server startup. dotnet ef dbcontext info --project app/api --configuration Release --no-build --json: passed with dummy localhost port 1 credentials; Npgsql provider confirmed without opening a database connection.- Final
npm run lintandnpm run typecheck: passed. Rootnpx tsc --noEmitalso passed after the final test assertion edit. npm test -- --list: passed, six tests discovered across three files.- Final
npm test: six passed in 17.8 seconds, including production web and Release API builds. An initial missing-config assertion checked the Node error message; it was corrected to check EF CLI stdout and the expected nonzero exit. git diff --check: passed. Final diff and added files reviewed for scope, generated artifacts, credentials, and duplicate configuration.- Moved source/assets verified against HEAD hashes. Generated .next, bin, obj, reports, and test results remain ignored. No real credentials added to the repo.
- Supabase automatic OAuth discovery initially failed with unsupported scopes. Explicit supported scopes succeeded after user browser authorization.
- A final-check attempt was blocked by approval-review usage limits. The user requested continuation and the retry was accepted.
Migrations, production API hosting, the
interactive /mcp panel, and the GitHub-hosted CI run have not been verified.
Existing Codex sessions may need reload to expose the newly added MCP tools.
The web build needs Google Fonts network access. npm reports the existing ESLint
9.39.5 as deprecated; upgrading unrelated framework tooling was left out of scope.
Review and commit the locally verified baseline on main, then run the workflow on GitHub before teammates branch from it. The first feature should agree on a requirement API contract and authorization model before schema work. Suggested independent ownership: requirement API/persistence, requirement UI against the agreed contract, GitHub integration investigation, and Playwright acceptance scenarios. Ask the user about branching before starting any new task.
- Branch: main, continuing the approved database setup. Application code unchanged.
- A temporary external C# probe initialized the existing EF context and attempted a read-only connection using app/api/.env.local, loaded explicitly for the probe. No credentials were printed. The normal API does not automatically load this file.
- The probe failed before authentication with SocketError NoData. DNS inspection found no IPv4 A record and one IPv6 AAAA record for the configured direct host. A TCP check to that IPv6 address on port 5432 returned NetworkUnreachable.
- No SELECT statement reached the database; no data or schema changes occurred.
- The user subsequently changed app/api/.env.local to the Session pooler. A retry reached that endpoint but failed TLS verification before authentication. A certificate diagnostic reported RemoteCertificateChainErrors / UntrustedRoot. The diagnostic rejected the untrusted certificate; verification was not bypassed.
- An earlier retry: Root Certificate was configured, but File.Exists returned false and Npgsql failed with DirectoryNotFoundException. No authentication or SQL execution occurred. Correct the certificate path to an existing local file.
- Previous retry: the certificate file exists, EF initialized, and the connection passed TLS verification with VerifyFull. PostgreSQL rejected authentication with SQLSTATE 28P01 (invalid_password). SELECT 1 did not execute.
- Latest retry succeeded: EF Core authenticated to Supabase through the session pooler with SSL Mode=VerifyFull and the configured CA certificate. SELECT 1 returned 1. No data or schema changes were made and no credentials were printed.
- Next step: configure the same connection string in API user-secrets or its environment. The normal API does not load .env.local; only the temporary probe loaded it explicitly. Live credentials and connectivity are verified for the probe, not yet configured for normal API startup.
- Verification: DNS A/AAAA checks and IPv6 TCP diagnostic completed; git diff --check passed. Only this handoff was updated in the repository.