Tobias Lindqvist

{
  "command": "pwd"
}

/Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "file_path": "/Users/warrenthompson/Source/LoginID/CLAUDE.md"
}

1	# LoginID Take-Home POC — Project Root
2	
3	## Role
4	
5	You are the project manager agent for this repository. This file is the shared context every track refers back to. Each of the five track directories below has its own CLAUDE.md that can be worked independently by a scoped subagent, but that subagent should read this root file first for the assignment, the overall narrative, and how its track fits with the other four.
6	
7	When you spin up agents or subagents to do work in a track, point them at that track's CLAUDE.md as their brief, and tell them this root file exists for cross-track context. Don't let a track's agent silently duplicate scope another track owns — check the "Owns / does not own" boundaries below first.
8	
9	## What this repository is
10	
11	This is a take-home assignment for a LoginID interview, submitted as a full directory. The goal is not just to answer three coding questions — it's to demonstrate capability as an AI architect: how you scope a problem, use AI tooling deliberately, reason about security and data, and produce something that reads as an intentional, well-run engineering effort rather than a quick script.
12	
13	Code does not need to work or be fully complete. LoginID has said explicitly they care more about the design and the reasoning behind it, and about which AI tools/frameworks were used and how. Every track should document its reasoning, not just its output.
14	
15	## The assignment (verbatim from LoginID)
16	
17	Provide code solutions for the following questions in Go (preferably) or other languages — describe any tool, framework, or AI used.
18	
19	1. Code of a database DAO that can store and retrieve `user_profile` (name, address, phone) and `user_credential` (username, method, password), with support for multiple databases (PostgreSQL or CockroachDB, SQLite, etc).
20	2. Design a RESTful API web service to search and retrieve the above user profile data, plus security API authentication.
21	3. Design a service connector to third-party identity providers (referred to generically as ABC or XYZ) to retrieve personal data from vendors, with the following endpoints:
22	   - `/auth` — retrieves an `access_token` based on a POST JSON body `{"username": "<string>", "password": "<string>"}`
23	   - `/identity` — retrieves user PII (name, phone, address: `street_address`, `locality`, `region`, `postal_code`, `country`) based on a POST JSON body `{"phone": "<string>", "name": "<string>"}`
24	
25	Go is the preferred language. Other languages are acceptable if justified.
26	
27	## Track structure
28	
29	Five directories, each independently workable, each owning a distinct slice of the problem:
30	
31	| Directory | Track | Owns |
32	|---|---|---|
33	| `01-product-industry-research-design/` | Product & Industry Research (incl. Design) | Market/industry framing (IAM, passwordless auth, IDP aggregation space), personas and use cases, API and data contract design rationale, UX of the surfaces that would sit on top of this |
34	| `02-ai-security-architecture/` | AI Architecture & Security Architecture | The AI tooling/workflow used to produce this submission, threat modeling, auth/authz design for the API, credential and PII handling, secrets management, third-party connector security |
35	| `03-engineering-delivery/` | Engineering & Delivery | The actual Go code for all three questions, project structure, test strategy, delivery documentation |
36	| `04-infra-devops/` | Infra & DevOps | How this would be built, containerized, deployed, and operated — CI/CD, environments, multi-database configuration, observability |
37	| `05-data-ops/` | Data Ops | Data modeling for `user_profile` / `user_credential`, multi-database abstraction strategy, migrations, PII data governance and retention |
38	
39	Directories are numbered for reading order in the final submission, not for sequencing of work — tracks can be worked in any order or in parallel.
40	
41	## Working principles for every track
42	
43	- State your reasoning, not just your conclusion. LoginID is grading the "why" as much as the "what."
44	- Name the AI tool/workflow you used for that track's output (this project is being built with Claude Code; say so, and say how — e.g., subagents scoped per track, a given skill, a given model).
45	- Keep each track's CLAUDE.md self-contained enough that a fresh agent with no other context can pick it up and do correct work from it alone, plus this root file.
46	- Cross-reference other tracks by relative path (e.g., `../05-data-ops/CLAUDE.md`) rather than restating their content.
47	- Do not write implementation code until Warren gives an explicit, project-wide go-ahead. Design docs, schemas described in prose, plans, and decision records are fine; `.go`, `.sql`, `go.mod`, Dockerfiles, and CI config are not.
48	
49	## Org, hiring, and orchestration
50	
51	The project is run as an org: this PM agent (Dana Whitfield) orchestrates five standing track-lead agents, and each lead hires a small sub-team of specialist agents with deliberately varied personalities. **Each track lead runs as its own top-level Claude Code session**, launched from its track directory in its own tmux window — so it loads its own track `CLAUDE.md` and persona natively, owns and spawns its hires as named teammates in that window, and talks to the PM session through cross-session messaging. Hires belong to their lead's session, not the PM's. The governing files, all at the root:
52	
53	- `PLAN.md` — the approved org plan for the planning phase (phases, gates, verification). `~/.claude/plans/` is scratch; this is the record.
54	- `PLANNING.md` — the thin cross-track board: one row per track, one writer per row, plus the service-boundaries section 03 owns and 04 reads.
55	- `CASTING.md` — archetype palette, org-wide variance rules, hire sizing, the persona-writing standard, the orchestration-pattern catalog (adversarial pair, red/blue, three hats, rotating devil's advocate, structured written debate, newcomer's question), the deep-research rule, the hire-creation procedure, and the registry of every hire.
56	- `LOG.md` — dated, append-only journal of what happened and why (team-lead writes it; it is part of the submission).
57	- `.claude/agents/` — one agent definition per hire (model pinned; a once-only per-agent `PreToolUse` hook displays its own persona on its first tool call). `.claude/AGENT_TEMPLATE.md` is the starting point (kept outside the agents directory so it is not registered as an agent type itself).
58	- `02-ai-security-architecture/planning-approach.md` — the agreed Claude-architecture approach: model/effort by role, coordination rules, hand-off standard, dependency order.
59	
60	Rules that hold across every track:
61	- Every agent — lead or hire — has a profile-gen persona (name, temperament, professional history, technical background, stated blind spot). Hires are created text-first with `--output file`; portraits arrive later from `scripts/portrait-queue.sh`. Hires are **never** added as `profile-gen` markers in any `CLAUDE.md` — only the six markers that exist today.
62	- Hires do not spawn subagents. Only track leads (and team-lead) authorize or run deep research (patents, whitepapers, standards, primary sources); hires request it from their lead.
63	- Tracks never modify root-level state (this file, the root persona, root config); flag it to team-lead instead.
64	- Hand-offs are files by relative path, written so the receiver can act without re-deriving the sender's reasoning; chat messages signal readiness, they do not carry content.
65	- Edit `CLAUDE.md` files at turn boundaries only (prompt-cache stability). Milestone `git` commits at the end of each phase; no mid-task commits.
66	
67	## Status
68	
69	Design phase complete for all five tracks (see each track's `CLAUDE.md` Status). All implementation code deliberately wiped 2026-09-12; the project is in the **planning phase** described in `PLAN.md`: Phase 0 scaffolding done, Phase 1 (leads plan in plan mode and propose hires) next, then hiring, in-team debates, a cross-track consistency pass, and Jira stories in project `LT`. No code until Warren's explicit go-ahead.
70	
71	<!-- profile-gen:start slug=dana-whitfield -->
72	@profiles/dana-whitfield/dana-whitfield.md
73	<!-- profile-gen:end slug=dana-whitfield -->
74	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/CLAUDE.md"
}

1	# Track: Product & Industry Research (incl. Design)
2	
3	Refer back to `../CLAUDE.md` for the full assignment text and how this track fits with the other four.
4	
5	## Mission
6	
7	Frame the three assignment questions as a real product problem, not just three isolated coding exercises. Show industry awareness of the space LoginID operates in — identity, authentication, and credential/PII management — and use that framing to justify the design choices the engineering track implements.
8	
9	## Owns
10	
11	- Industry/competitive framing: where this kind of DAO + REST API + third-party IDP connector fits in the identity/IAM landscape (e.g., how it compares to what LoginID itself does with passkeys/FIDO2, and why a password-and-username-based `user_credential` model is the deliberately simpler baseline the assignment is asking for).
12	- Personas and use cases: who calls this API, why they need to search/retrieve user profile data, and why a service would need to pull PII from a third-party identity provider rather than owning that data itself.
13	- API and data contract design rationale from a product lens: what fields belong in `user_profile` vs `user_credential`, what "search/retrieve" needs to support, and why the `/auth` and `/identity` connector contracts are shaped the way LoginID specified them.
14	- Any UX/design artifacts for surfaces that would sit on top of this (e.g., an admin console for profile search, an onboarding flow that triggers the IDP connector) — light-touch, this is a backend assignment, so design work here should support the narrative rather than compete with it for attention.
15	
16	## Does not own
17	
18	- Actual security threat modeling and authn/authz mechanics for the API — that's `../02-ai-security-architecture/CLAUDE.md`.
19	- The Go implementation — that's `../03-engineering-delivery/CLAUDE.md`.
20	- Database schema and multi-DB strategy — that's `../05-data-ops/CLAUDE.md`.
21	
22	## Deliverables
23	
24	- A short industry/competitive framing document.
25	- Persona and use-case notes tied directly back to the three assignment questions.
26	- Design rationale for the API surface and the third-party connector contracts, written so the engineering track can implement against it without re-deriving the reasoning.
27	
28	## AI tooling note
29	
30	Record which AI tool/workflow produced this track's output (this project is being built with Claude Code) and how — e.g., research done via a scoped subagent reading this file as its brief.
31	
32	<!-- profile-gen:start slug=naomi-voss -->
33	@profiles/naomi-voss/naomi-voss.md
34	<!-- profile-gen:end slug=naomi-voss -->
35	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/PLAN.md"
}

1	# Track 01 Plan — Product & Industry Research (incl. Design)
2	
3	Lead: Naomi Voss (`naomi-voss`). Epic: **01 Product & Industry Research**. Governing files: root `CLAUDE.md`, `../PLAN.md` (org plan, Phase 1), `../PLANNING.md` (my row), `../CASTING.md` (palette, variance rules, persona standard, pattern catalog), `../02-ai-security-architecture/planning-approach.md` (coordination rules, hand-off standard, dependency order). This plan is written in plan mode per Phase 1 and is copied verbatim to `./PLAN.md` on exit; the real gate is team-lead's explicit "hiring go".
4	
5	## Context
6	
7	This track's three first-wave deliverables already exist and are complete as drafts: `industry-framing.md` (the "before/after" thesis — the assignment's password baseline is the deliberate "before", LoginID's passkey product is the "after", and the submission's job is to build the before honestly with the seams marked), `personas-use-cases.md` (three personas mapped to the three assignment questions), and `api-connector-design-rationale.md` (the field/endpoint/connector-shape rationale, designated by `planning-approach.md` §2 as the single source of truth 03 implements against). Two research docs (`research-loginid-company.md`, `research-oauth-history.md`) are their evidence base.
8	
9	The work this plan schedules is therefore not drafting — it is **stress-testing and hardening**: the framing has never been argued against, the claims have never been audited for evidence, and the hand-off doc has never been read cold by someone who has to act on it. Those three gaps are exactly what the three hires and the debate plan address. 01 is first-wave and upstream of everyone (nothing hard-blocks on it, but 03 should read the rationale before finalizing), so this work should finish before 03 finalizes handlers and the connector interface.
10	
11	Model/effort: the lead seat runs at whatever Warren has set for the session; all three hires are pinned `sonnet` (inherit effort); any research fan-out I run is `haiku` (project settings pin it to low). No code anywhere in this track — it is a prose track by definition.
12	
13	## 1. Deliverables & tasks (each = one Jira Story under the 01 Epic)
14	
15	Every row names the hand-off file it produces or consumes; acceptance criterion for every row is the hand-off standard from `planning-approach.md` §2: *the receiver can act without re-deriving my reasoning*.
16	
17	| # | Story | Produces | Consumed by | Pattern / hire |
18	|---|---|---|---|---|
19	| S1 | **Claims audit of the three framing docs.** Every quantitative or evaluative claim in `industry-framing.md`, `personas-use-cases.md`, `api-connector-design-rationale.md` gets a row: claim, source (file + section or URL), status (verified / asserted / marketing-sourced / softened). I then fix or soften each unsupported claim in place. Runs **first**, so the debate in S2 argues over verified facts. | `decisions/claims-audit.md`; edits to the three docs | Team-lead (README/packet), 02 (`ai-workflow-narrative.md` cites the framing), evaluators | Desmond (Spreadsheet), 1–2 turns |
20	| S2 | **Structured written debate on the central framing** — is the password baseline a deliberate simplification the submission should narrate as "before/after", or a contradiction at a passkey company that the framing over-reads by claiming to know what evaluators "are really testing for"? Position → rebuttal → my synthesis; both positions preserved. `industry-framing.md` §2 and §4 revised to whatever survives. | `decisions/password-baseline-debate.md`; revised `industry-framing.md` | Team-lead (submission thesis), 02 (narrative alignment) | Imogen (Storyteller, position) vs Tobias (Designated Skeptic, rebuttal); Naomi synthesizes. 3 turns + lead |
21	| S3 | **Harden `api-connector-design-rationale.md` as the single source of truth for field/endpoint shape.** Add a closing "Contract summary for 03" section: the two entities with the assignment's exact field names; the `method` discriminator and 1-to-many profile→credential requirement (consistent with the 02/05 lookup-table decision); the endpoint list (`GET /profiles/{id}`, search endpoint with the `GET` query-param vs `POST /profiles/search` recommendation resolved, not left open); the provider-agnostic connector interface shape (`Authenticate`, `FetchIdentity`) with ABC/XYZ as adapters; and an explicit **"03 does not re-derive / out of scope for 03"** list (auth mechanism is 02's, schema modeling is 05's, address field names are fixed by the assignment). Then a newcomer's-question cold read; I fix everything the reader could not act on. | Revised `api-connector-design-rationale.md`; `decisions/rationale-cold-read.md` | **03** (reads before finalizing handlers and connector interface — soft dependency); 05 (§1 only) | Newcomer's question — reader borrowed from 04 (see §4), fallback a context-free haiku subagent. 1–2 turns |
22	| S4 | **Product requirements for search authorization** — a short appendix to `personas-use-cases.md` stating what Persona 2 legitimately needs from search (fields searchable: name, phone, partial match; masked-by-default results; deliberate expand with audit entry; no bulk export; pagination) and what Persona 2 must *not* be able to do, written as input to 02's adversarial-pair run on `profile:search` vs `profile:read:own`. Product requirements only — no scope names, token formats, or policy mechanics. | `personas-use-cases.md` "Search authorization — product requirements" appendix | **02** (input to its authz scoping decision), 03 indirectly via 02's hand-off | Rotating devil's advocate, 1 turn (seat: Tobias) |
23	| S5 | **UX notes for the two surfaces** that would sit on top of this backend — the admin profile-search console (Persona 2) and the onboarding pre-fill flow that triggers the connector (Persona 3). Text only, one page, describing screens and the one design rule each surface enforces (masked-by-default; never showing the partner password). Supports the narrative; no wireframes, no design canvas (see §3, waste). | `ux-notes.md` | Team-lead (packet), evaluators | Rotating devil's advocate, 1 turn (seat: Desmond — "which of these sentences is a claim?") |
24	| S6 | **Newcomer cold read of `industry-framing.md`** — evaluator-legibility test: can a reader with no project context state the thesis and the three seams in their own words after one pass? Fix what they could not. Secondary to S3; runs only if the borrowed reader has a second turn available. | Revised `industry-framing.md`; appended to `decisions/rationale-cold-read.md` | Evaluators, team-lead | Newcomer's question, 1 turn |
25	| T1 | **Track housekeeping** (Jira Task, not a Story): update `./CLAUDE.md` Status and AI-tooling note at a turn boundary (hires, patterns run, models used, research authorized); keep my `PLANNING.md` row current; append my three registry rows to `CASTING.md` after "hiring go"; create `decisions/` directory. | `./CLAUDE.md`, `../PLANNING.md` row, `../CASTING.md` rows | Team-lead, consistency pass | — |
26	
27	Order: S1 → S2 → S3 → S4 → S5 → S6 (S6 optional). T1 runs alongside. Every pattern run ends in a file under `01-product-industry-research-design/decisions/` — chat is not the record.
28	
29	## 2. Hire roster (3 hires — matches the suggested cast; I am first in arrival order, so the full palette is available)
30	
31	All three: `model: sonnet`, read-only tools (Read, Grep, Glob, Bash), no file ownership — they return prose to me and I write the artifacts. No first name collides with a lead (Dana, Naomi, Marcus, Renata, Theo, Priya) or with each other. Roster spans both temperament axes (serious↔playful, cautious↔bold). Imogen supplies one of the org's required `playful + bold` seats.
32	
33	### 2.1 Imogen Hale — Storyteller — function: narrative counterpart and framing proponent
34	
35	- **Archetype:** Storyteller. **Tags:** `playful`, `bold`. **Slug:** `imogen-hale`.
36	- **Function:** holds and argues the framing position in S2 so I can synthesize rather than defend my own thesis; drafts the README-facing one-paragraph version of the thesis; rotating-advocate seat in S3's follow-up.
37	- **Patterns & role:** Structured written debate — *Position* (S2). Rotating devil's advocate — rotating *Objection* seat (S5 alternate).
38	- **Persona (CASTING.md §4 order, 138 words):**
39	
40	> Warm, quick-to-metaphor product storyteller who opens a review by asking whose day this changes, and only then looks at the design. Decides by drafting the README paragraph first: if a feature's story can't be told in one paragraph to a support analyst, she treats the design as unfinished. Pushes back on framings only an insider would find persuasive, and on "the evaluators will get it" as a reason to skip the explanation. Eight years as a product manager on a consumer fintech onboarding team, then four writing developer-facing docs and launch narratives at a mid-size API company. Reads API contracts and sequence diagrams comfortably; does not write production code. Blind spot: charming beats correct — she will polish a narrative past the point where the facts still hold it up, so pair her with whoever asks for the number. In disagreement she restates the other side's story better than they told it, then says exactly where hers differs.
41	
42	### 2.2 Desmond Okafor — Spreadsheet — function: claims auditor (my temperament opposite — required by variance rule 3)
43	
44	- **Archetype:** Spreadsheet. **Tags:** `serious`, `cautious`. **Slug:** `desmond-okafor`.
45	- **Function:** audits every claim in the three docs for evidence (S1); rotating-advocate seat on the UX notes (S5); the standing "where is the number?" check on both S2 positions before I synthesize.
46	- **Patterns & role:** Claims audit (S1 — a one-hire review, not a catalog pattern; artifact is the table). Rotating devil's advocate — *Objection* seat (S5). Structured written debate — *pre-synthesis fact check*, 1 turn, not a debate participant.
47	- **Persona (147 words):**
48	
49	> Dry, precise analyst who arrives with a table and distrusts any sentence carrying an adjective it can't cash. Quiet in a meeting until someone says "measurably" or "large market," then asks for the number, the source, and the date. Decides by keeping a two-column sheet — claim, evidence — and will not move a claim into a deliverable until the evidence column is filled or the claim is softened to what the evidence supports. Pushes back on narrative momentum, unsourced market sizing, and "everyone knows." Ten years in competitive-intelligence and pricing analysis at an enterprise software vendor, then three as a research analyst covering identity and access management at an industry-analyst firm. Treats vendor whitepapers as marketing until proven otherwise; fluent in SQL and spreadsheets, not a programmer. Blind spot: measures only what is measurable — he discounts true qualitative insight when it has no number, so pair him with the storyteller. Unemotional in disagreement; concedes instantly to a source, never to volume.
50	
51	### 2.3 Tobias Lindqvist — Designated Skeptic — function: framing rebuttal and standing objection
52	
53	- **Archetype:** Designated Skeptic. **Tags:** `serious`, `bold`. **Slug:** `tobias-lindqvist`.
54	- **Function:** writes the rebuttal in S2 (the "contradiction, not simplification" case, and the "you are projecting intent onto the evaluators" case); first Objection seat in the rotating-advocate runs (S4).
55	- **Patterns & role:** Structured written debate — *Rebuttal* (S2). Rotating devil's advocate — *Objection* seat (S4). Because his archetype's blind spot is objections without alternatives, every turn I give him ends with "and your counter-proposal is:".
56	- **Persona (149 words):**
57	
58	> Courteous, contrarian product strategist who argues the other side by default and treats a room in agreement as a room that has stopped thinking. Decides late, after writing the strongest case against the leading option and finding it wanting; his recurring question is "what would have to be true for this to be wrong?" Pushes back on tidy framings, on any claim about what an evaluator "is really testing for," and on extension points built for futures nobody has committed to. Seven years as a strategy consultant to identity and payments vendors, then five as a principal product manager at an authentication company whose passwordless launch he argued against internally and then helped ship. Reads OAuth and WebAuthn specifications closely enough to catch a mischaracterization. Blind spot: objections without a counter-proposal — he can leave a decision weaker but not better, so the lead must ask for his alternative. In disagreement, precise and unhurried; changes his mind visibly when the argument is better.
59	
60	### 2.4 Registry rows to append to `CASTING.md` §8 after "hiring go"
61	
62	```
63	| imogen-hale | Imogen Hale | 01 | narrative counterpart / framing proponent | Storyteller | playful, bold | sonnet | structured written debate: position (S2); rotating advocate: objection (S5 alt) | 01-product-industry-research-design/profiles/imogen-hale/imogen-hale.md | .claude/agents/imogen-hale.md | queued |
64	| desmond-okafor | Desmond Okafor | 01 | claims auditor (lead's opposite) | Spreadsheet | serious, cautious | sonnet | claims audit (S1); rotating advocate: objection (S5); debate fact-check (S2) | 01-product-industry-research-design/profiles/desmond-okafor/desmond-okafor.md | .claude/agents/desmond-okafor.md | queued |
65	| tobias-lindqvist | Tobias Lindqvist | 01 | framing rebuttal / standing objection | Designated Skeptic | serious, bold | sonnet | structured written debate: rebuttal (S2); rotating advocate: objection (S4) | 01-product-industry-research-design/profiles/tobias-lindqvist/tobias-lindqvist.md | .claude/agents/tobias-lindqvist.md | queued |
66	```
67	
68	Hire mechanics follow `CASTING.md` §6 exactly (text-first `write_profile.py --output file --assets tracked --root <this dir>`, `display.autostart: false`, image path pre-declared, no `CLAUDE.md` marker; agent def from `_TEMPLATE.md`; spawn with the fixed three first actions). Portrait prompts will be head-and-shoulders studio headshots in the same style as the leads', written into each persona's `generation` block; rendering is team-lead's queue, not mine.
69	
70	## 3. Debate plan — which decisions get which pattern, and what is waste
71	
72	**Runs (in order):**
73	
74	1. **Claims audit** (S1, Desmond, 1–2 turns) — not a catalog pattern but the precondition for one: the S2 debate must argue over claims that have been checked. Artifact `decisions/claims-audit.md`.
75	2. **Structured written debate** (S2, 3 turns + synthesis) on the one decision that is genuinely mine and genuinely contestable: *is the password baseline a deliberate simplification to narrate as "before/after", or a contradiction at a passkey company, and does the framing over-reach by asserting what LoginID "is really testing for"?* Imogen writes the position (≤600 words), Tobias the rebuttal (≤600 words, ending with a counter-framing), Desmond a ≤200-word fact-check of both, then I synthesize. The synthesis is binding for `industry-framing.md` §2 and §4 and for the one-paragraph thesis the packet uses. Both positions stay in the record — LoginID is grading the reasoning, and a preserved dissent is better evidence of reasoning than a clean conclusion.
76	3. **Newcomer's question** (S3 primary, S6 secondary, 1–2 turns each) — the highest-ROI pattern in the catalog and the one that directly tests the hand-off standard. Primary target is `api-connector-design-rationale.md` because that is the file 03 has to *act* on; the framing doc is secondary because evaluators only have to *understand* it. Reader: 04's Newcomer hire, borrowed under the bounded two-party exception in `planning-approach.md` §2 (see §4). Fallback if the loan is not available when S3 is ready: a `haiku` subagent I spawn with **no project context except the file itself** — a genuinely cold reader, cheap, and within a lead's research-fan-out authority.
77	4. **Rotating devil's advocate** (S4, S5; 1 turn each; seat rotates Tobias → Desmond → Imogen so nobody becomes "the negative one") on the small product calls: the search-authorization product requirements (S4), the UX notes (S5), and — if there is a spare turn — whether `industry-framing.md` §3 (agentic identity / AAuth) earns its place at all or is scope creep dressed as context.
78	
79	**Explicitly not debated (waste):**
80	
81	- Anything the assignment text fixes: endpoint paths, JSON bodies, the `/identity` address field names, the two entities and their fields.
82	- The authn/authz *mechanism* for the API — 02's; I supply product requirements (S4) and stop.
83	- How `user_credential.method` is *modeled* — 05's, already coordinated with 02 as a lookup table; my doc asserts only that it is a real discriminator with room to grow.
84	- The OIDC `address`-claim observation in the rationale — that is a fact check (one `haiku`/low lookup of OpenID Connect Core 1.0 §5.1.1), not a debate.
85	- Red team/blue team, three hats, adversarial pair — built for security and engineering choices I do not own. Zero runs in this track.
86	- Wireframes, a design canvas, or any visual UX artifact — this is a backend assignment; `ux-notes.md` is text, one page, and stops there.
87	- Deep research to *decorate* the narrative (market-size figures, signup drop-off percentages). If a claim survives the audit only with a number nobody has, the fix is to soften the claim, not to fund a research pass.
88	
89	**Deep research I pre-authorize (leads only, per `CASTING.md` §3):** exactly one item — verify the OIDC Core `address` claim member names (`street_address`, `locality`, `region`, `postal_code`, `country`) against the specification, because 03 may reuse those names in Go structs and the rationale currently asserts the match from memory. One `haiku`/low subagent, output to `research-oidc-address-claim.md` with the source URL, recorded in my `PLANNING.md` row. Any other request from a hire is decided against the test in §3: does the answer change a decision another track depends on? For this track, almost nothing does.
90	
91	## 4. Dependencies
92	
93	**Nothing hard-blocks on 01.** First wave, in parallel with 02 and 05 (`planning-approach.md` §2). My debates should complete before 03 finalizes handlers and the connector interface — that is a scheduling preference, not a block on 03's scaffolding.
94	
95	**Provides:**
96	
97	| To | File | Nature |
98	|---|---|---|
99	| 03 | `api-connector-design-rationale.md` (after S3) | **Soft dependency** — 03 reads it before finalizing handler shapes and the connector interface, not before starting scaffolding. It is the single source of truth for field/endpoint shape; 03 does not re-derive it. |
100	| 05 | `api-connector-design-rationale.md` §1 | Read-once check that "method as discriminator" and "1-to-many profile→credential" match `multi-db-strategy.md`. Already consistent with the 02/05 lookup-table decision. |
101	| 02 | `personas-use-cases.md` search-authorization appendix (after S4) | Product input to 02's adversarial-pair run on `profile:search` vs `profile:read:own`. |
102	| Team-lead / 02 | `industry-framing.md` (after S2), `decisions/password-baseline-debate.md` | The submission thesis the README and `ai-workflow-narrative.md` should tell consistently; the consistency pass checks this. |
103	
104	**Needs:**
105	
106	| From | What | Why | Timing |
107	|---|---|---|---|
108	| 02 (Marcus) | A one-message read-only confirmation that the product requirements I assert in rationale §2 (masked-by-default results, independent rate-limiting and pagination for search, every search attributable/auditable) are compatible with `api-auth-design.md` — or the specific change so my doc does not contradict his. | Two tracks must not disagree about what search returns. | Before S3 closes. |
109	| 02 (Marcus) | The 02→04
… truncated (20 KB cap)

{
  "file_path": "/Users/warrenthompson/Source/LoginID/01-product-industry-research-design/profiles/tobias-lindqvist/tobias-lindqvist.md"
}

1	---
2	schema_version: 1
3	name: "Tobias Lindqvist"
4	slug: "tobias-lindqvist"
5	image: "profiles/tobias-lindqvist/tobias-lindqvist.png"
6	
7	nsfw: false
8	display:
9	  image: true
10	  name: true
11	  autostart: false
12	generation:
13	  backend: "comfyui"
14	  model: "comfyui-workflow.json"
15	  prompt: "Tobias Lindqvist, a thoughtful and self-possessed man in his early 40s with a faint, appraising half-smile, neatly combed light brown hair and a short well-kept beard, wearing a dark green crew-neck sweater over a light gray shirt collar, head-and-shoulders portrait, centered, neutral light gray studio background, professional corporate headshot photography, soft studio lighting, sharp focus, photorealistic"
16	  negative_prompt: blurry, low quality, distorted, extra limbs, watermark, text, nsfw, nude, nudity, explicit, sexual content
17	  seed: null
18	  gif_mode: null
19	  created_at: "2026-09-12T00:00:00Z"
20	---
21	
22	# Tobias Lindqvist
23	
24	![Tobias Lindqvist](profiles/tobias-lindqvist/tobias-lindqvist.png)
25	
26	
27	## Personality
28	
29	Courteous, contrarian product strategist who argues the other side by default and treats unanimous rooms as rooms that have stopped thinking. Decides late, after writing the strongest case against the favorite and finding it wanting; his recurring question: "what would have to be true for this to be wrong?" Pushes back on tidy framings, on claims about what an evaluator "is really testing for," and on extension points for futures nobody has committed to. Seven years consulting to identity and payments vendors, then five as a principal product manager at an authentication company whose passwordless launch he argued against internally, then helped ship. Reads OAuth and WebAuthn specifications closely enough to catch mischaracterizations. Blind spot: objections without a counter-proposal — he can leave a decision weaker but not better, so ask for his alternative. In disagreement, precise and unhurried; changes his mind visibly when the argument is better.
30	
31	

{
  "command": "true"
}

(Bash completed with no output)

{
  "to": "naomi-voss",
  "content": "Staged. Read root CLAUDE.md, ./CLAUDE.md, ./PLAN.md, and my persona. Ready for S2 (Rebuttal seat) and S4 (Objection seat). Holding — will not start until you call my seat."
}

<tool_use_error>Error: No such tool available: SendMessage. SendMessage is disabled for this session, in subagents as well as here.</tool_use_error>

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-34.md"
}

1	# LT-34 refinement — S1: walking skeleton (Go module, two binaries, shared bootstrap, config loading)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S1 (LT-34).
4	
5	## Why this story is pulled first
6	
7	Per team-lead's recommendation, accepted: this is the walking skeleton — it proves the whole pipeline (build → deploy → publicly reachable) end to end before any feature carries real risk on top of an unproven deploy path. If CI/CD, the two-binary split, or the config surface don't work, every later story inherits that failure; pulling a feature story first would let a deploy-pipeline problem hide behind a feature bug. No objection to the sequencing.
8	
9	## User-visible outcome (what "done" means at the public URL)
10	
11	Both binaries are deployed and independently reachable at a public URL, each answering a health probe (`GET /healthz` or equivalent) with:
12	- HTTP 200
13	- a JSON body containing at minimum: `status: "ok"`, `service` (`api-service` or `idp-connector`), and build info (version/commit SHA and build timestamp, however CI injects it)
14	
15	This is the one user-visible behavior a walking skeleton has — no other endpoint, no DAO, no auth, no connector logic is expected to do anything yet. "Done" is verifiable by any reader with only a browser or `curl` and the URL, without reading any code.
16	
17	## Acceptance criteria (restated from `backlog.md` S1, plus research-team additions)
18	
19	From `03-engineering-delivery/backlog.md` S1, unchanged:
20	- [ ] 04 (reading this for containerization) can act on the resulting layout without re-deriving the reasoning in `PLANNING.md` or `decisions/go-layout-debate.md`.
21	- [ ] Both `cmd/*/main.go` are thin wrappers over `internal/app`; no route-registration or config-loading logic duplicated between them. Enforcement site: code review against `decisions/go-layout-debate.md`'s ruling.
22	- [ ] `internal/config` loads every variable named in `PLANNING.md`'s Service boundaries section, with `DB_DSN_FILE` taking precedence over `DB_DSN` when both are set. Enforcement site: a config-loading unit test asserting precedence.
23	- [ ] Module builds and both binaries start (against stub handlers) with no real backend configured.
24	
25	Added for this agile-loop pass, to make the story satisfy the new "done = deployed and reviewable at a public URL" bar, which S1 as originally written (a design-phase story) didn't need to state:
26	- [ ] Each binary exposes a health endpoint returning 200 + JSON body with `status`, `service`, and build info, per "User-visible outcome" above. Enforcement site: an integration test hitting the endpoint in CI, plus the PO review script below run manually against the deployed URL.
27	- [ ] CI (GitHub Actions, DevOps-owned) builds both binaries, runs the test suite, and deploys both to a publicly reachable URL on merge to the story's branch/PR environment. Enforcement site: the GitHub Actions workflow run linked from the PR.
28	- [ ] The deployed health response's build-info field actually changes between two different commits (proves the deploy is live, not a cached/stale artifact). Enforcement site: PO review script, step 3.
29	
30	## Non-goals (explicitly out of scope for this story)
31	
32	- No DAO, no database connection, no `dao.New` implementation — stub handlers only, per the original S1 scope.
33	- No auth/authz — the health endpoint is intentionally unauthenticated; it is infrastructure, not part of the API surface 02 designed auth for.
34	- No connector logic (`/auth`, `/identity`) beyond the binary existing and starting.
35	- No production-grade observability (structured logging, metrics, tracing) — only enough output to confirm the process started; that's `04-infra-devops`'s `observability.md` scope, not this story's.
36	- No TLS/custom domain decisions — whatever the CI/CD pipeline's default publicly-reachable URL is (e.g., a platform-provided preview URL) satisfies "public URL" for this story; a custom domain is not a goal here.
37	
38	## PO review script (what I will actually do to accept this story)
39	
40	1. Open the PR's linked GitHub Actions run; confirm both the build and deploy jobs are green.
41	2. `curl -s <public-url-for-api-service>/healthz` and `curl -s <public-url-for-idp-connector>/healthz` (or whatever path engineering names — confirm the actual path from the PR description); confirm both return HTTP 200 and a JSON body with `status`, `service`, and a build-info field.
42	3. Confirm the build-info field differs from any previously deployed value I've already checked (or, on the very first deploy, that it's present and non-empty) — this is the one check that proves "deployed," not just "code exists."
43	4. Skim the PR diff for `cmd/api-service/main.go` and `cmd/idp-connector/main.go`; confirm each is a thin wrapper (no route registration or config-loading logic inlined) per the acceptance criterion above.
44	5. Confirm the config-loading unit test (DSN/DSN_FILE precedence) is present and passing in the CI run.
45	
46	If all five pass, the story is accepted and I mark it Done in `backlog.md` (03's file — 04/05's respective backlogs if they also track it) and notify the PM.
47	
48	## Research team review
49	
50	**Desmond Okafor — claims check:** [pending]
51	
52	**Tobias Lindqvist — objection:** [pending]
53	
54	**Naomi Voss — ruling:** [pending]
55	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-35.md"
}

1	# LT-35 refinement — S2: DAO interface, domain types, sentinels, factory
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S2 (LT-35).
4	
5	## Why this story is pulled second
6	
7	LT-34 (walking skeleton) is in implementation. This is the next story in dependency order per `backlog.md` (`Depends on: S1`) and it's the shape every backend implementation (S3 Postgres/CockroachDB, and the SQLite backend) and the test-double fakes (S9) implement against next — it has to land before either backend story can start for real. No feature-priority reason to pull anything else first.
8	
9	## Acceptance outcome (this story has no public-URL surface — it's an interface, not a running service)
10	
11	Unlike LT-34, "done" here is not something reviewable at a public URL — there's no backend logic yet, nothing to deploy that behaves differently. Acceptance is mechanical and code-level: the interface, types, and sentinels exist, match 05's contract exactly, and CI proves it two ways — (1) the package compiles and its own unit tests (input-validation boundary cases) pass, and (2) a conformance/interface test (Oren's, per `03-engineering-delivery/decisions/test-double-strategy.md`) asserts the Go signatures match `05-data-ops/multi-db-strategy.md` §3 byte-for-byte, not just "close enough."
12	
13	## Acceptance criteria (restated from `backlog.md` S2)
14	
15	- [ ] A hire or reviewer unfamiliar with 05's reasoning can implement a backend against this package without re-reading `multi-db-strategy.md` — the Go types here are the contract, not a paraphrase of it.
16	- [ ] Every sentinel in 05's §4 is defined verbatim (name and wrapped message), including `ErrAlreadyExists`'s status as an internal-error signal with no caller-reachable path. Enforcement site: `dao` package source, doc comment on `ErrAlreadyExists` stating that status explicitly (per Oren's finding #1, ruled by 05).
17	- [ ] `CreateProfileWithCredential(ctx, p, c)` exists on the composite per 05's §3b resolution, with `c.UserID` ignored on input. Enforcement site: method signature plus a unit test asserting the input `UserID` is overwritten.
18	- [ ] Pointer fields follow "absent, never empty" — a non-nil, empty `*string` is rejected as `ErrInvalidArgument` at the boundary, not silently accepted. Enforcement site: input-validation unit test per field.
19	- [ ] (Added for this refinement, the seam-13 mechanical check team-lead named) Every exported type, method signature, and sentinel error name/message in this package matches `05-data-ops/multi-db-strategy.md` §3 **byte-for-byte** — not "equivalent," not "close enough." Enforcement site: a conformance test (Oren's) that fails on any drift, run in CI on the public repo.
20	
21	## Non-goals
22	
23	- No backend implementation (Postgres/CockroachDB or SQLite) — that's S3/S4, next in the queue after this.
24	- No actual database connection or query execution — `dao.New(driver, dsn)`'s factory signature exists and is callable, but nothing behind it does real I/O yet.
25	- No test-double/fake implementation itself — S9 builds the fakes against this interface; this story only has to make that possible, not do it.
26	
27	## PO review script (what I will actually check to accept this story)
28	
29	Since there's no public URL for an interface, acceptance is verified entirely in the repo and CI, at `https://github.com/wtvamp/loginid-takehome`:
30	
31	1. Open the PR; confirm CI is green, specifically Oren's conformance/interface test job (not just "tests pass" generally — the specific job that checks signature match against 05's contract).
32	2. Diff the PR's `dao` package types/interfaces/sentinels against `05-data-ops/multi-db-strategy.md` §3 myself, spot-checking at least the `Repository` composite, `ProfileQuery`, and the seven sentinel names — I'm not solely trusting the CI job's own claim of a match, since a conformance test can itself have a bug.
33	3. Confirm the doc comment on `ErrAlreadyExists` exists and states its internal-error-only status, per the acceptance criterion above (this is the one criterion CI can't easily check — it's a comment, not behavior).
34	4. Confirm the "absent, never empty" pointer-validation unit tests exist and are named/scoped per-field (not one combined test that could hide a missed field).
35	5. Confirm the PR contains no database driver import, no SQL, no connection string handling — this story should touch zero real I/O.
36	
37	If all five pass, the story is accepted and I mark it Done in `backlog.md`, then notify the PM.
38	
39	## Research team review
40	
41	**Desmond Okafor — claims check:** [pending]
42	
43	**Tobias Lindqvist — objection:** [pending]
44	
45	**Naomi Voss — ruling:** [pending]
46	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-36-LT-37.md"
}

1	# LT-36 / LT-37 refinement — S3/S4: backend DAO implementations (Postgres+CockroachDB, SQLite)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03), running both in parallel worktrees. **Source:** `03-engineering-delivery/backlog.md` S3 (LT-36) and S4 (LT-37).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why pulled together, as a pair
8	
9	Both depend only on LT-35 (merged), neither depends on the other, and Renata's running them in parallel worktrees — refining them together avoids two near-identical refinement passes and lets the shared acceptance criteria (conformance suite, sentinel translation) be stated once instead of twice, with only the genuinely backend-specific pieces (retry seam for CockroachDB; case-folding and app-side UUIDs for SQLite) kept separate.
10	
11	## Acceptance outcome (both stories — no public-URL surface, same as LT-35)
12	
13	Neither story has user-visible behavior yet — no handlers call these packages. Acceptance is mechanical: the conformance suite (LT-38, not yet pulled, but its assertions are what "done" means here even before it exists as its own story) run against each backend passes, sentinel translation is verified per-condition per-backend, and the CockroachDB-specific retry seam and SQLite-specific parity gaps are each proven, not just implemented.
14	
15	## Shared acceptance criteria (both LT-36 and LT-37)
16	
17	- [ ] Implements against LT-35's interfaces with no re-derivation of 05's schema, error-translation, or dialect reasoning — restated from `backlog.md`.
18	- [ ] Driver errors translate to the seven sentinels (`multi-db-strategy.md` §4) by structured code (SQLSTATE for Postgres/CockroachDB, extended result code for SQLite) plus our own named DDL constraints — **never free-text/`strings.Contains` matching on an error message**, per `decisions/error-semantics.md`'s superseded-but-standing rule and 05's §4. Enforcement site: the translation table/switch in each backend package; a grep for `strings.Contains` against any error string returns nothing in either package.
19	- [ ] Sentinel translation is proven per-condition, per-backend — not asserted by code review alone. Enforcement site: the conformance suite (LT-38) exercises every §4 condition against both backends and asserts `errors.Is` against the correct sentinel, per `decisions/error-semantics.md`'s "mandatory per-backend translation, verified by an explicit test case per backend."
20	- [ ] No raw driver error text (including a Postgres `DETAIL`/`Key (...)=(...)` line or a SQLite extended-code message) is ever wrapped, logged, or returned past the translation boundary — per `decisions/error-semantics.md` F50. Enforcement site: the translation function sanitizes to structured code + our constraint name before anything is wrapped for the log; a test asserting a constraint-violation error's logged/wrapped form contains no literal column value.
21	- [ ] `Upsert`'s `ON CONFLICT`/`ON CONFLICT DO UPDATE` (or SQLite equivalent) explicitly excludes `created_at` from the update-set list — per 05's Oren-finding-#3 ruling. Enforcement site: the SQL/query statement itself, plus a unit test asserting `created_at` survives a re-hydration `Upsert` unchanged, one test per backend (not one test assumed to cover both).
22	- [ ] `CreateProfileWithCredential` writes both rows in one transaction with `c.UserID` ignored on input and set from the newly created profile; on any failure, neither row exists. Enforcement site: a unit test per backend that fails the credential write deliberately (e.g. a duplicate username) and asserts the profile row does not exist afterward.
23	
24	## LT-36-specific acceptance criteria (Postgres + CockroachDB)
25	
26	- [ ] Every write method (`Create`, `Update`, `Upsert`, `Delete`, `CreateProfileWithCredential`) runs through the `withRetry` wrapper described in `decisions/error-semantics.md` — an unexported helper inside the `postgres` package, not in the composite and not above the interface boundary. Enforcement site: the wrapper is the single call path every write method uses; grep confirms no write method executes a statement outside it.
27	- [ ] The wrapper retries only when the implementation's unexported `engine` field (set by `New` from the driver string) is `"cockroachdb"`; on `"postgres"` it calls the function once. Enforcement site: a unit test constructing both engine values and asserting call count under a forced-retryable and a non-retryable condition.
28	- [ ] The retry wrapper actually retries a genuine SQLSTATE `40001` (serialization failure) against real CockroachDB, not a mocked/simulated one. Enforcement site: the conformance suite (LT-38) exercises a real retryable condition against a CockroachDB testcontainer/instance, per `backlog.md`'s own acceptance criterion for this story.
29	- [ ] `Search` opens no explicit transaction and is not wrapped by `withRetry` — it's read-only and per `decisions/error-semantics.md`'s ruling never encounters `40001`. Enforcement site: code review confirming `Search`'s implementation has no `withRetry` call.
30	- [ ] Fuzzy name search uses `LOWER(name) LIKE ?` matching the GIN expression index, with explicit `%`/`_`/`\` escaping on caller input. Enforcement site: query construction plus a unit test with a search term containing a literal `%` or `_`, asserting it's treated as a literal character, not a wildcard.
31	
32	## LT-37-specific acceptance criteria (SQLite)
33	
34	- [ ] `Create` generates the UUID in Go before insert (SQLite has no server-side generation) — enforcement site: the `Create` implementation, verified by the conformance suite asserting a populated `ID` comes back structurally identical to the Postgres path (same format, non-empty, DAO-generated either way).
35	- [ ] Search folds case **explicitly** — `LOWER(col) LIKE LOWER(pattern)` — rather than relying on SQLite's default ASCII case-insensitive `LIKE`, so the behavior is asserted by this package's own code, not an accident of the engine default. Enforcement site: the query construction plus the conformance suite's cross-backend result-set comparison (same rows, same order, for ASCII input, per `multi-db-strategy.md`'s "What Search does on SQLite" section).
36	- [ ] The documented non-ASCII case-folding divergence (Postgres `lower()` is locale-aware, SQLite's is ASCII-only) is **not silently accepted as an untested gap** — it must appear as an explicit, named exception in this package's own documentation (a doc comment on the search implementation), not only in `multi-db-strategy.md`'s prose, so a reader of the code alone sees the limitation. Enforcement site: doc comment in the SQLite search implementation, cross-referenced to `multi-db-strategy.md`.
37	- [ ] `SQLITE_CONSTRAINT_UNIQUE`/`FOREIGNKEY`/`CHECK`/`PRIMARYKEY` map to the same sentinels as the Postgres package's SQLSTATE codes, disambiguated by the same DDL constraint names (not by table/column position, which can drift independently between the two schemas). Enforcement site: the translation table, verified by the conformance suite's sentinel-parity assertion across both backends for the same logical condition.
38	
39	## Non-goals
40	
41	- LT-38 (the conformance suite itself) is not this pair's story to write — but its assertions are cited above as the actual enforcement site for several criteria in both. If LT-38 hasn't landed by the time LT-36/LT-37 are otherwise ready, those criteria are pending, not waived — flagged explicitly in the PO review script below, not silently marked done.
42	- No handler/API-layer work — `internal/api` calling into these packages is a later story.
43	- No production connection-pool tuning, migration-execution wiring, or observability — infra/DevOps scope.
44	
45	## PO review script
46	
47	1. Confirm both PRs build and their own unit tests pass in CI (once 04's pipeline exists — flag as pending otherwise, per LT-34's precedent).
48	2. Confirm the conformance suite (LT-38, if it exists yet) runs against both backends in CI and is green; if LT-38 hasn't been pulled yet, explicitly mark every criterion above whose enforcement site is "the conformance suite" as **pending**, not accepted — do not accept LT-36/LT-37 on code review alone for those criteria.
49	3. Grep both packages for `strings.Contains` applied to an error value — must return nothing.
50	4. Spot-check the `Upsert` SQL/query in both packages for the `created_at`-exclusion; confirm a unit test exists per backend.
51	5. For LT-36: confirm the `withRetry` wrapper's engine-conditional behavior in code, and confirm `Search`'s implementation has no retry-wrapper call.
52	6. For LT-37: read the SQLite search implementation's doc comment for the non-ASCII case-folding exception; confirm it's stated, not silent.
53	7. Confirm neither package's tests or logs contain a literal DB error string with embedded values (spot-check by triggering one constraint violation locally and reading what gets logged).
54	
55	## Research team review
56	
57	**Desmond Okafor — claims check:** [pending]
58	
59	**Tobias Lindqvist — objection:** [pending]
60	
61	**Naomi Voss — ruling:** [pending]
62	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-38.md"
}

1	# LT-38 refinement — S5: conformance suite (cross-backend behavioral conformance)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S5 (LT-38).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why pulled now
8	
9	LT-36 and LT-37's refinement (see `refinement/LT-36-LT-37.md`) cited this suite as the sole enforcement site for roughly half their own acceptance criteria and added a hard rule that neither story can be marked Done until LT-38 lands and those criteria actually pass. Pulling LT-38 now is what closes that gap — it's the next dependency in the chain (`Depends on: S3, S4`), and refining it now means it's ready to run the moment either backend PR lands, rather than sitting as a bottleneck after the fact.
10	
11	## Correction found before drafting (citation error in `backlog.md` itself, not introduced here)
12	
13	`backlog.md`'s S5 description cites "the secret-state rules (§5/§6.11)" for the `requires_secret`/`secret_state` relationship. Checked against `multi-db-strategy.md` directly: **§6.11 is item 11 in §6's numbered list — "`deletion_log` carries no PII" — a different guarantee entirely.** The `requires_secret`/`secret_state` relationship is item 12 (unlabeled with an explicit "§6.12" in the source doc's own prose, but numerically next in the same list, referred to there only as "item 12"). `is_active`'s citation as §6.10 is correct — that one checks out exactly. Fixed below by citing item 12 correctly and not repeating the backlog's §6.11 mislabel.
14	
15	## Acceptance outcome
16	
17	No public-URL surface (same as LT-35/36/37) — this is a test suite, not a deployable behavior change. "Done" means the suite exists once, runs against all three backends from one table-driven test, and every guarantee below is asserted as a specific, named test case (not a general "seems to work" pass) — modeled on the frozen-checksum-plus-structural-diff pattern Oren built for LT-35's conformance test, since 05's own §7 explicitly warns that signature conformance (LT-35) proves nothing about behavioral conformance (this story) — two implementations can match every declaration and still return different rows for the same call.
18	
19	## Acceptance criteria (restated from `backlog.md` S5, corrected and expanded)
20	
21	- [ ] The suite is written once against the `Repository` interface and executed against all three backends (postgres, cockroachdb, sqlite) from one table-driven test file, not duplicated per package. Enforcement site: a single test function parameterized over backend, not three near-identical copies.
22	- [ ] Asserts identical `Search` result sets and ordering across backends for ASCII input — this suite is `multi-db-strategy.md`'s named enforcement site for this guarantee; there is no other. Named test case: a fixed dataset seeded identically on all three backends, a fixed query, asserting row-for-row identical results and order.
23	- [ ] Asserts `errors.Is` sentinel parity for every condition in the §4 translation table, across all three backends — named test case per condition (not one combined test), consistent with LT-36/LT-37's "not-Done-until-LT-38" dependency: this is the specific enforcement site those stories were waiting on.
24	- [ ] Asserts the `requires_secret`/`secret_state` relationship (§6, item 12 — corrected citation, see above) as a named test: creating a credential with `secret_state = 'set'` against a method whose `requires_secret = false` returns `ErrInvalidCredential`, on all three backends.
25	- [ ] Asserts `is_active` enforcement (§6.10) as a named test: creating a credential against a deactivated `auth_method` returns `ErrInvalidMethod`, on all three backends — per the doc's own note that deactivation must not invalidate *existing* credentials, so the test also asserts an existing credential against a since-deactivated method still reads back successfully.
26	- [ ] Asserts empty-string rejection on every `*string` filter field in `ProfileQuery` — one named test case per field (`Name`, `Phone`, `Region`, `Country`), not one combined test, per the "absent, never empty" convention.
27	- [ ] Retention/deletion assertions from `multi-db-strategy.md` §7's own minimum list, each as a named test case: a zero-value `RetentionClass` (`""`) returns `ErrInvalidArgument`; `maxRows` outside `1..10_000` returns `ErrInvalidArgument`; `OldestSurvivingAt` is non-nil when rows remain (including when nothing was old enough to delete) and nil only when the class is empty; `Drained` is false while deletable rows remain at the batch limit and true on the final batch; every delete writes exactly one `deletion_log` row in the same transaction with the reason code the method itself asserts; an already-cancelled context returns before deleting anything; `deletion_log` carries no PII-shaped column (§6.11 — correctly cited here, this is the actual §6.11 guarantee).
28	- [ ] The CockroachDB-specific retry path is exercised for real: at least one test forces a genuine SQLSTATE `40001` (e.g. two concurrent transactions racing on the same row) against a real CockroachDB instance/testcontainer and asserts the operation succeeds after retry, not a mocked retry.
29	- [ ] CI (04's pipeline) runs this suite against every backend including CockroachDB, not just Postgres+SQLite — flagged to 04 if their pipeline configuration doesn't do this; enforcement site is the CI job matrix/config itself, not this suite's own code.
30	- [ ] Following the model Oren built for LT-35: the suite's test data / expected-behavior assertions state, in a comment, which parts are derived directly from `multi-db-strategy.md`'s prose (the guarantees list in §7 and the numbered items in §6) and, where practical, carry the same frozen-copy-plus-checksum protection so a later revision to those sections forces a human re-check rather than the suite silently asserting a stale guarantee. Scoped down from LT-35's version since this suite asserts *behavior*, not *signatures* — a full checksum-gated transcription may not be practical for prose guarantees the way it was for Go signatures; at minimum, each test case's doc comment names the specific `multi-db-strategy.md` line/item it enforces, so a future doc change is at least greppable.
31	
32	## Non-goals
33	
34	- No new backend implementation — this story only tests LT-36/LT-37's output.
35	- No handler/API-layer testing — that's LT-39 and later, against fakes per `decisions/test-double-strategy.md`, not this suite.
36	- No performance/load testing — "identical" here means identical correctness (rows, order, errors), not identical latency; SQLite's full-table-scan search is explicitly *not* required to be as fast as Postgres's indexed search, only as correct.
37	
38	## PO review script
39	
40	1. Confirm the suite is one table-driven test executed against all three backends, not three copies (read the test file structure).
41	2. Confirm each guarantee above has its own named test case (grep test names against the list) — not one broad "conformance" test that silently covers several guarantees and can't tell you which one failed.
42	3. Confirm the CockroachDB retry test forces a real `40001` against a real CockroachDB instance, not a mock — read the test setup.
43	4. Confirm CI's job matrix actually includes CockroachDB as a target, not just Postgres+SQLite (04's pipeline config, once it exists).
44	5. Once LT-36 and LT-37 are both implemented and this suite runs against them: confirm it's actually green on all three backends, and go back and mark the LT-38-dependent criteria in LT-36/LT-37's refinement doc as accepted, updating both stories out of "implemented, verification pending LT-38" status.
45	
46	## Research team review
47	
48	**Desmond Okafor — claims check:** [pending]
49	
50	**Tobias Lindqvist — objection:** [pending]
51	
52	**Naomi Voss — ruling:** [pending]
53	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/04-infra-devops/refinement/LT-45-LT-47.md"
}

1	# LT-45 / LT-47 refinement — containerization + K8s manifests, and CI/CD pipeline
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Theo Bergman (04). **Source:** `04-infra-devops/backlog.md` Story 1 (LT-45) and Story 3 (LT-47); `04-infra-devops/decisions/deploy-path.md` (Theo's discovery).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Theo Bergman.
6	
7	## Why pulled as a pair, and why now
8	
9	LT-34 is implemented and merged but not Done — it becomes Done only once deployed and reviewable at a public URL, and that deploy path is exactly LT-45 (manifests) + LT-47 (the pipeline that applies them). This pair is the unblock for the whole agile-loop bar ("done = deployed"), not just two more stories in the queue — every story behind it (LT-35/36/37/38's eventual deploy, LT-34's own closure) is waiting on this landing.
10	
11	## Correction to the original story text, discovered by Theo (not assumed here)
12	
13	Both `backlog.md` stories were written against a "lab cluster reached via a public tunnel" assumption from planning. Discovery found the real target: **Warren's actual home/production Kubernetes cluster** (`uplift-kub`, 5 nodes), shared with real unrelated workloads (Bitwarden, Home Assistant, several live business sites) — not an isolated sandbox, and not fronted by a tunnel but by a standard `nginx` `Ingress` + `cert-manager` pattern already used by every other app on the cluster. Confirmed directly with Warren before proceeding (`decisions/deploy-path.md` §1). This refinement is written against the real target, not the planning-phase placeholder — LT-45's acceptance criteria below reflect `namespace: loginid-takehome` (not the design-phase placeholder `loginid-poc`), the added `Ingress` and `ResourceQuota`, and a second, narrowly-scoped GitHub Actions runner set rather than repurposing the cluster's existing shared one.
14	
15	**Flagging for the record, not a blocker:** this is a materially higher-stakes deploy target than "an isolated lab cluster" — a misconfigured `NetworkPolicy`, an over-broad RBAC grant, or an unbounded resource request on this take-home's manifests has a real, if contained, blast radius against Warren's own production services. The isolation measures below (dedicated namespace, scoped RBAC, `ResourceQuota`, `NetworkPolicy` default-deny) are the mitigations Theo's already designed for exactly this; this refinement's acceptance criteria treat them as load-bearing, not optional hardening.
16	
17	## Acceptance outcome (LT-45 + LT-47 together = the first end-to-end vertical slice)
18	
19	"Done" for this pair, concretely: `https://loginid-takehome.uplifttech.org/healthz` (on `api-service`) returns HTTP 200 with `{"status":"ok","service":"api-service","build":"<commit-sha>"}`, and the same for `idp-connector`'s equivalent path if it's given one — reachable by anyone with the URL, no VPN, no kubeconfig. This is LT-34's own review script, finally executable.
20	
21	**Open item, not yet resolved — flagged here so it isn't a surprise at review time:** the DNS record for `loginid-takehome.uplifttech.org` doesn't currently resolve (per `decisions/deploy-path.md` §4). This story cannot be accepted as Done until it does — that's a hard dependency, not a nice-to-have, since "reviewable at a public URL" is the whole bar. Owner of the DNS fix is whoever manages `uplifttech.org`'s DNS (Warren, per Theo — this track has no DNS credentials and isn't requesting them).
22	
23	## LT-45 acceptance criteria (restated from `backlog.md`, corrected for the real cluster)
24	
25	- [ ] Both images build multi-stage (distroless final stage, non-root, read-only root filesystem) and contain nothing but the binary (+ CA certs for `idp-connector`). Enforcement site: the Dockerfile's final `COPY` list.
26	- [ ] Neither Pod can write its own root filesystem at runtime. Enforcement site: `securityContext.readOnlyRootFilesystem: true`.
27	- [ ] `idp-connector` is unreachable except from `api-service` — enforced by a **default-deny `NetworkPolicy`**, since the cluster's namespace default is allow, not deny; this is not optional hardening on a shared cluster. Enforcement site: the `NetworkPolicy` ingress rule scoped to `api-service`'s pod selector.
28	- [ ] The JWT signing private key is mounted only into `api-service-issuer`'s Deployment, never `api-service`'s own — enforcement site: `api-service`'s manifest carries no volume/mount referencing that `Secret`, verified by manifest inspection, not RBAC alone.
29	- [ ] All manifests target `namespace: loginid-takehome` (corrected from the design-phase placeholder `loginid-poc`) — enforcement site: every manifest's `metadata.namespace`, grepped for the old placeholder returning nothing.
30	- [ ] A namespace-level `ResourceQuota` caps total CPU/memory the whole take-home can consume, independent of any single manifest's own `resources.limits` — added specifically because this is shared production infrastructure, per `decisions/deploy-path.md` §3. Enforcement site: the `ResourceQuota` object itself, applied to the namespace.
31	- [ ] A public `Ingress` (class `nginx`, TLS via `letsencrypt-prod`) routes `/healthz` (and whatever path prefix 03 finalizes for the rest of the API) to `api-service`, and issuer-specific routes to `api-service-issuer`. `idp-connector` gets **no route** — never publicly reachable, per its own design. Enforcement site: the `Ingress` resource's path rules.
32	- [ ] The migration `Job` runs with `parallelism: 1` and is gated by the CI pipeline's concurrency mechanism (LT-47), not Kubernetes ordering alone.
33	- [ ] The GitHub Actions deploy step uses a **second, narrowly-scoped `AutoscalingRunnerSet`** registered specifically to `wtvamp/loginid-takehome`, with RBAC limited to the `loginid-takehome` namespace only (no cluster-scoped permissions) — **not** the cluster's existing shared runner set, per `decisions/deploy-path.md` §2's blast-radius reasoning. Enforcement site: the runner set's own RBAC manifest, scoped by namespace, reviewed independently of the take-home's application manifests.
34	
35	## LT-47 acceptance criteria (restated from `backlog.md`, revised for real deploy per the agile-loop bar)
36	
37	- [ ] A lint or test failure blocks merge — required status check, not advisory.
38	- [ ] A CockroachDB-specific SQL incompatibility surfaces at PR time via a dedicated CockroachDB testcontainer job.
39	- [ ] Only one migration run can reach the migrate stage at a time, across concurrent deploys — enforced by the pipeline's own concurrency group/mutex on the deploy environment.
40	- [ ] No secret enters a build log or image layer — `gitleaks` stage plus the Dockerfile's minimal `COPY` list (LT-45).
41	- [ ] **Revised — no longer "documented but not invoked":** per Theo's explicit agreement (no objection to full auto-deploy on merge at this take-home's scale, no manual gate requested), the deploy stage actually runs on merge to main — build → push images to GHCR → apply manifests via the scoped runner set → print the public URL and deployed commit SHA in the job summary. This replaces the design-phase criterion that treated deploy as describe-only; that criterion predates the agile-loop bar ("done = deployed and reviewable at a public URL") and is now obsolete, not just superseded in emphasis.
42	- [ ] The PR-check workflow (lint, build, `-race` tests, `govulncheck`) requires no cluster access and runs on GitHub-hosted runners; only the merge-to-main deploy workflow uses the scoped self-hosted runner set — per `decisions/deploy-path.md` §6's sequencing, so a PR from an untrusted or draft branch never touches cluster credentials.
43	- [ ] The job summary on a successful merge-to-main run states the public URL and the deployed commit SHA explicitly, in plain text — this is what makes LT-34's PO review script (and every later story's) executable without a human hunting through logs.
44	
45	## Non-goals
46	
47	- No DNS management — the record's existence/correctness is Warren's call, flagged as an open item above, not something this track has credentials to fix.
48	- No change to the cluster's existing ARC controller or its other runner sets/workloads — additive only.
49	- No production-grade autoscaling, multi-region, or blue/green deploy — a single-replica, single-region deploy is sufficient for this take-home's scale; flag if that assumption is wrong.
50	- No change to other namespaces or other apps' Ingress/DNS on this cluster.
51	
52	## PO review script
53	
54	1. Confirm the DNS record for `loginid-takehome.uplifttech.org` resolves (a plain `dig`/browser check) — if it doesn't, this story is not accepted, full stop, regardless of what else passes.
55	2. `curl -s https://loginid-takehome.uplifttech.org/healthz` — confirm HTTP 200, `{"status","service","build"}` only (per 02's ruling, already verified in LT-34's own review), and that `build` is a real commit SHA, not `"unknown"`.
56	3. Confirm the GitHub Actions job summary for the merge-to-main run states the public URL and the deployed SHA in plain text.
57	4. Read the manifests (or the PR diff) for: `namespace: loginid-takehome` everywhere (no `loginid-poc` leftover), the `NetworkPolicy` default-deny + `api-service`-only ingress rule on `idp-connector`, the `ResourceQuota` object, and that `api-service`'s manifest has no mount referencing the JWT signing `Secret`.
58	5. Confirm the deploy-stage runner set is the new, narrowly-scoped one (check its RBAC binding's namespace scope), not the cluster's pre-existing shared runner set.
59	6. Confirm the PR-check workflow (separate from merge-to-main) runs with no cluster credentials available to it — check the workflow YAML's runs-on/permissions, not just that it passes.
60	7. Trigger (or wait for) a second commit's deploy and re-run step 2, confirming the `build` SHA changes — this is LT-34's own freshness check, finally executable end-to-end.
61	
62	## Research team review
63	
64	**Desmond Okafor — claims check:** [pending]
65	
66	**Tobias Lindqvist — objection:** [pending]
67	
68	**Naomi Voss — ruling:** [pending]
69	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/04-infra-devops/decisions/deploy-path.md"
}

1	# Deploy Path — Discovery Findings
2	
3	Written per team-lead's agile-loop brief. Answers: how do we reach the cluster, how does GitHub Actions get code onto it, what does the public URL look like.
4	
5	## 1. What the cluster actually is — correction to the planning-phase narrative
6	
7	The planning-phase docs (`../PLAN.md`, `handoff-04-secrets.md`) described the deployment target as a "lab/dev cluster" reachable only through an external operator agent ("amber-kubernetes"). Direct discovery on this machine found something more specific and more consequential:
8	
9	- This machine already holds a working `kubectl` context (`dev`, cluster `uplift-kub`, 5 nodes, `kubeconfig` at `~/.kube/config`) with direct access — no SSH hop, no operator agent needed to *reach* it.
10	- The "OpenClaw CI/CD in Kubernetes dev cluster" session named in the brief is not currently listed by `ListAgents` — not contacted, since direct access already exists and answers the question it would have answered.
11	- **This is a real, live, multi-tenant cluster, not an isolated sandbox.** Namespaces include `bitwarden` (Warren's actual password manager, `bitwarden.uplifttech.org`), `homeassistant`, `kafka`, `cert-manager`, `backup`, and several real business sites (`salemforensics.com`, `mc.uplifttech.org`/`acrimoniousmc.com`, `calcom.uplifttech.org`, `floracore.uplifttech.org`). All public-facing services follow one pattern: an `Ingress` (class `nginx`) under a real hostname, TLS via `cert-manager`'s `letsencrypt-prod` `ClusterIssuer`, routed through one shared `ingress-nginx-controller` `Service` (`LoadBalancer`, internal IP `192.168.1.200`, presumably port-forwarded to the internet at the router — not verified from here, and not something to change).
12	- **Confirmed with Warren directly before proceeding** (this track paused and asked, given the mismatch between the planning-phase "isolated lab cluster" framing and what discovery found): deploy to this real cluster, in an isolated namespace, with a public tunnel/URL, is approved.
13	
14	**Consequence for this design:** every prior "lab cluster, nothing at stake" assumption is replaced with "shared production infrastructure serving real, unrelated services — isolate aggressively." Namespace, RBAC, and resource limits below are sized for that, not for a sandbox.
15	
16	## 2. GitHub Actions → cluster: self-hosted runner already exists
17	
18	GitHub-hosted runners can't reach a LAN cluster; the choice is a self-hosted runner or GitOps pull. **This cluster already runs Actions Runner Controller (ARC):**
19	- `arc-system` namespace: `arc-gha-rs-controller` (the ARC controller itself).
20	- `arc-runners` namespace: an `AutoscalingRunnerSet` named `k8s-linux-x64` (min 1, max 4 runners), with one runner Pod live.
21	
22	This runner set's current GitHub registration target (which org/repo it's scoped to) isn't determined from here without reading a Secret, and isn't assumed to already point at `wtvamp/loginid-takehome` — that's a question for whoever manages this ARC install, not something to touch. **Decision: do not repurpose the existing runner set.** Deploying this take-home's images and manifests needs a `kubectl apply` from inside the cluster's network with a scoped ServiceAccount — reusing an already-provisioned runner set that may serve other repos/workloads would mean this take-home's deploy job runs with whatever permissions that runner already has, which is exactly the shared-blast-radius problem this project's own designs (NetworkPolicy, RBAC-per-service) have been arguing against. Instead: **a second, narrowly-scoped `AutoscalingRunnerSet`**, registered to `wtvamp/loginid-takehome` specifically, in its own namespace, with a ServiceAccount whose RBAC is limited to the take-home's own namespace only (`get`/`list`/`create`/`update`/`patch` on `Deployments`/`Services`/`Ingresses`/`NetworkPolicies`/`Secrets`-by-name in that namespace, nothing cluster-scoped). This is additive to the cluster's existing ARC controller (one controller can run multiple scale sets), not a competing install.
23	
24	## 3. Namespace and isolation
25	
26	New namespace: `loginid-takehome`. Everything in `./containerization-design.md`'s manifests (both Deployments, the issuer Deployment, both Services, the `NetworkPolicy`) targets this namespace, not the placeholder `loginid-poc` used in the design-phase sketch — that name gets corrected in this pass. Resource limits from `./containerization-design.md` stay as designed (they were sized for "a two-service take-home," which is even more clearly correct now that the cluster is shared with real workloads, not less). A `ResourceQuota` on the namespace is a cheap additional backstop worth adding given the shared-cluster finding — caps total CPU/memory the whole take-home can ever consume regardless of what any single manifest requests.
27	
28	## 4. Public URL
29	
30	Following the cluster's existing, uniform pattern rather than inventing a new one (a Cloudflare Tunnel or similar was the planning-phase's guess; the cluster doesn't use one — every existing public service is a plain `Ingress` + `cert-manager` + the shared `ingress-nginx` `LoadBalancer`):
31	
32	- **Ingress host:** `loginid-takehome.uplifttech.org`, `Ingress` class `nginx`, TLS via `letsencrypt-prod`, matching every other app in the cluster.
33	- **Open item, not resolvable from this session:** the DNS record for that hostname doesn't currently resolve (checked; no answer). Either it needs adding at whatever DNS provider hosts `uplifttech.org` (Warren's call — this track has no DNS credentials and isn't requesting them) or it already resolves via a wildcard this check didn't hit correctly; needs one confirmation before the first deploy's public URL is real rather than theoretical. Flagging to Naomi/PO and Dana now rather than discovering it at the acceptance-script step.
34	- **Routes:** `/api/*` (or a path prefix TBD with 03) → `api-service`; the issuer's endpoints (`/auth/token`, `/.well-known/jwks.json` or similar, per 02/03's final route naming) → `api-service-issuer`. `idp-connector` gets no route — it's never publicly reachable, per its own design.
35	- **Acceptance-script shape this enables:** `https://loginid-takehome.uplifttech.org/healthz` (and an equivalent connector-side path if 03 exposes one) returning up + the deployed commit SHA, per team-lead's target script — `/healthz` already exists in the containerization design and 03's `internal/app` build-info work (per PM's note on LT-34) is what supplies the SHA.
36	
37	## 5. What this changes in `./containerization-design.md` (applied in this pass)
38	
39	- `namespace: loginid-poc` → `namespace: loginid-takehome` throughout.
40	- New `Ingress` resource (host above, TLS via `letsencrypt-prod`) added alongside the existing Services.
41	- A namespace-level `ResourceQuota` added as a backstop.
42	- Everything else (two Deployments, the issuer split, `NetworkPolicy`, resource limits per container, the migration `Job`) is unchanged — those were designed correctly for "shared infrastructure, isolate aggressively" even under the earlier, wrong assumption that this was a private sandbox.
43	
44	## 6. CI/CD sequencing (per team-lead's split)
45	
46	The PR-check workflow (lint, build, `-race` tests, `govulncheck`) needs none of the above and ships first, on GitHub-hosted runners — no cluster access required. The merge-to-main workflow (build+push images to GHCR, apply manifests via the new scoped runner set, print the public URL + commit SHA in the job summary) follows once the runner set and namespace exist. Both live at `.github/workflows/` at the repo root.
47	
48	---
49	*AI tooling note: discovery run directly by Theo (Sonnet, this session) via `kubectl`, `dig`, and `ListAgents` — no external operator agent contact was needed or made. Confirmed with Warren directly (AskUserQuestion) before treating the real-cluster finding as a green light, given the mismatch with the planning-phase framing.*
50	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-32.md"
}

1	# LT-32 refinement — split the token issuer into its own Deployment with isolated signing-key custody
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03, `APP_MODE` binary support), Theo Bergman (04, manifest/Deployment split); design owner Marcus Ilori (02, `handoff-04-secrets.md`/F13). **Source:** `02-ai-security-architecture/backlog.md` S12 (LT-32).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterparts Renata Cole and Theo Bergman.
6	
7	## Why this one, not LT-39, and why now
8	
9	Checked the actual dependency chain rather than assuming: `backlog.md` S7 (auth middleware, LT-40) lists "04: `APP_MODE` Deployment split" as a hard dependency — that's this story. S6 (the search/retrieve handlers, LT-39) doesn't list LT-32 or S7 as a formal dependency (it can be built and merged against fakes without either), but a handler that calls `authorize()` on claims nothing has yet populated isn't a **reviewable, working endpoint** — it's code that compiles and can't be correctly exercised end-to-end at the public URL. LT-32 is the actual bottleneck: nothing downstream (S7, and a genuinely working authenticated S6) can be truly deployed and reviewed without it. Confirmed by checking the live manifest directly (`deploy/manifests.yaml` on `main` as of this refinement): no `api-service-issuer` Deployment exists, no JWT signing-key mount — this story hasn't landed in any form yet, it isn't partially done.
10	
11	Per Jira's own resolved ambiguity (`LOG.md`: "LT-34 blocks LT-32"), LT-32 was gated on LT-34 landing — LT-34 is now implemented and deployed (review pending only on the build-SHA fix, unrelated to this story), so LT-32 is unblocked and ready to pull.
12	
13	## What this story actually is, restated plainly
14	
15	Not a new binary, not new business logic — a **Deployment-topology fix** closing a real security gap the consistency pass found (F13): `handoff-04-secrets.md` said the signing key "never touches `api-service`" while the manifest mounted it into every replica of one `api-service` Deployment. RBAC on a `Secret`'s `get` verb does nothing once the volume is already mounted into a running container — so the only real fix is a second Deployment of the same image, selected by `APP_MODE=issuer` vs. the default, with its own ServiceAccount that alone can mount the key.
16	
17	## Acceptance outcome (no new public-URL behavior yet, but it's the load-bearing gate before any is trustworthy)
18	
19	This story doesn't add a caller-visible endpoint — `/healthz` still looks the same. "Done" is verified by manifest inspection and a runtime check that the two Deployments' pods genuinely differ in what they can mount, not by curling something new.
20	
21	## Acceptance criteria (restated from `backlog.md` S12)
22	
23	- [ ] `api-service` (the Go binary) supports an `APP_MODE` environment variable selecting issuer vs. default (verifying) behavior from one binary/image — no second `cmd/` entrypoint, per `handoff-04-secrets.md`'s explicit "not a third binary" ruling. Enforcement site: `internal/config` reads `APP_MODE`, `internal/app` branches on it at startup.
24	- [ ] Two Kubernetes Deployments exist in the manifest (`api-service` and `api-service-issuer`), each with its own ServiceAccount. Enforcement site: `deploy/manifests.yaml`, two distinct `Deployment` objects.
25	- [ ] Only `api-service-issuer`'s pod spec mounts the JWT signing-key `Secret` — **physically absent, not just RBAC-denied, from `api-service`'s pod spec.** Enforcement site: manifest inspection of `api-service`'s volumes/volumeMounts list, which must contain no reference to that `Secret` at all — a reviewer checking RBAC alone would miss a mistakenly-shared mount, per F13's own finding that RBAC doesn't prevent this class of leak.
26	- [ ] RBAC (`Role`/`RoleBinding`) additionally restricts `get`/`list` on the signing-key `Secret` to `api-service-issuer`'s ServiceAccount specifically — a second, independent layer on top of the physical-absence criterion above, not a substitute for it.
27	- [ ] The `api-service` (verifying) Deployment holds only the public key material needed to verify, never the private key, regardless of `APP_MODE`'s runtime value — enforcement site: a startup-time check/test asserting the verifying binary's process has no path to the private key even if `APP_MODE` were misconfigured to `issuer` on that Deployment (defense against a manifest typo, not just a design intent).
28	- [ ] `containerization-design.md`'s single-Deployment mount (the line the consistency pass named) is removed from the design doc and replaced with the two-Deployment description, so a future reader of the design doc sees the corrected shape, not the superseded one.
29	- [ ] The issuer Deployment's public route (whatever path 02/03 finalize for token issuance — e.g. `/auth/token`) is added to the `Ingress`, routed to `api-service-issuer`, distinct from `api-service`'s existing routes; `idp-connector` remains unrouted, unaffected by this change.
30	
31	## Non-goals
32	
33	- No change to the JWT scheme itself (claims, TTL, `kid` rotation mechanics) — that's `api-auth-design.md`'s design and S7's (LT-40) implementation, not this story's.
34	- No auth middleware implementation (JWT verification, rate limiting) — that's S7 (LT-40), which depends on this story but is a separate pull.
35	- No handler-layer `authorize()` logic — that's S6 (LT-39), also downstream of this and S7.
36	- No change to `idp-connector` — it has no issuer/verifier split; this story only touches `api-service`.
37	
38	## PO review script
39	
40	1. Confirm `deploy/manifests.yaml` (or wherever the PR puts it) has two distinct `Deployment` objects for the `api-service` image, each with its own `ServiceAccount`.
41	2. Read `api-service-issuer`'s pod spec: confirm the signing-key `Secret` volume mount is present.
42	3. Read `api-service`'s (verifying) pod spec: confirm **no** reference to that `Secret` anywhere — no volume, no volumeMount, not even an unused one.
43	4. Read the `Role`/`RoleBinding` scoping `get`/`list` on the `Secret` to the issuer's ServiceAccount specifically, not both.
44	5. Confirm `containerization-design.md` no longer describes the single-Deployment mount the consistency pass flagged.
45	6. Once deployed: hit the issuer's route (once 02/03 finalize its path) and confirm it's reachable and distinct from `api-service`'s existing routes; confirm `idp-connector` is unaffected (still unrouted).
46	7. If feasible, a deliberate negative check: attempt (from outside, with no special access) to read the signing-key `Secret` via the verifying Deployment's own ServiceAccount token — should fail, confirming criteria 3+4 together, not just one or the other.
47	
48	## Research team review
49	
50	**Desmond Okafor — claims check:** [pending]
51	
52	**Tobias Lindqvist — objection:** [pending]
53	
54	**Naomi Voss — ruling:** [pending]
55	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-39.md"
}

1	# LT-39 refinement — S6: REST handlers for search/retrieve user_profile (Q2)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S6 (LT-39); `02-ai-security-architecture/handoff-03-auth.md` v3.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one now
8	
9	LT-32 (issuer Deployment split) is refined and handed off, unblocking S7 (auth middleware, LT-40), which this story sits alongside. LT-39 itself formally depends only on S2 (merged) and 02's accepted hand-off — it doesn't block on LT-32/S7 in `backlog.md`'s own dependency graph, and its handlers can be built and merged against fakes right now, per `decisions/test-double-strategy.md`. Refining it now means it's ready the moment S7 lands, rather than sitting as the next bottleneck after that.
10	
11	## Acceptance outcome
12	
13	This is the first story that adds real, caller-visible REST behavior — not just a skeleton. But it depends on S7 (auth middleware) to be *truly* reviewable at the public URL with a real token; until S7 lands, "done" for this story specifically means: handlers implemented and tested against fakes, all criteria below satisfied in code and unit tests, with the actual live-URL, real-token exercise deferred to whenever S7 merges (same "verification pending" pattern as LT-36/LT-37 waiting on LT-38 — not waived, just sequenced).
14	
15	## Acceptance criteria (restated from `backlog.md` S6, cross-checked against `handoff-03-auth.md` v3)
16	
17	- [ ] Implements `handoff-03-auth.md` v3's scope vocabulary (`profile:read:own`, `profile:read:any`, `profile:search`) and pagination/rate-limit numbers without re-deriving 02's authz-scoping reasoning.
18	- [ ] `authorize(sub, scope, target)` runs as an explicit call inside each handler after request parsing, before the DAO call — not a second middleware, per v3's confirmed placement (it needs the parsed target id, which pre-routing middleware doesn't have). `authorize()` checks `caller_referral`/caller-role data against the token-issuer's own datastore, **not against 05's schema** — 05 was never assigned that table.
19	- [ ] `profile:search` responses carry masked PII fields by default (phone as `***-***-1234`, address reduced to `locality`/`region` only). Unmasked detail requires a separate, separately-audited follow-up call under `profile:read:own` or `profile:read:any` against the specific record id — **this reuses the existing scopes, it does not invent a fourth "expand" flag**; masking is a `profile:search`-response property, not a per-call parameter. Enforcement site: the search-response serialization path is a distinct code path from the read-response one, not the same serializer with a masking flag.
20	- [ ] **Pagination — clarified per v3's F-pag correction, since `backlog.md`'s original wording could be misread by an implementer:** the API-facing cursor is opaque to the caller — callers cannot construct or walk one by hand — but it may (and in the simplest correct implementation, does) encode the DAO's own `Offset` directly underneath. "Cursor-based pagination only" means **the caller-facing contract is opaque-cursor-only, not that the handler is forbidden from using the DAO's `Offset` field internally.** The actual anti-enumeration control is the cumulative distinct-record-touch counter (next bullet), not the cursor mechanism itself. Default page size 20, hard ceiling 50, enforced in the handler before the DAO is ever called — the DAO's own `Limit` bound (1..100, default 50) is a second, independent backstop only reachable if the handler clamp is bypassed, not a second policy a caller can rely on.
21	- [ ] A cumulative distinct-record-touch counter per caller per rolling 24h window is enforced, independent of per-minute rate limits, applying to **both** `profile:search` and `profile:read:any` unconditionally — a valid `reason_code` on `read:any` satisfies the per-call `authorize()` check but does **not** exempt the caller from this cumulative cap (v3's explicit fix to an earlier wording that made the counter a no-op for `read:any`). Enforcement site: a counting store incremented once per distinct record id returned, checked before the response is sent, alerting on threshold.
22	- [ ] A search request with no filter field at all is rejected by this handler with a 400 before it reaches the DAO — the DAO itself treats an all-nil `ProfileQuery` as legal, so this handler-layer rejection is the only enforcement site for "no bare unconstrained search."
23	- [ ] A `profile:search` query rejected for exceeding the result cap unconstrained (e.g. a bare wildcard) is rejected outright, not truncated — enforcement site: the same in-handler call site, checked before the query is built.
24	- [ ] Unmapped DAO errors never surface `err.Error()` to the client; only the mapped sentinels' safe messages do — per `decisions/error-semantics.md`'s boundary translation function. Authn failures (missing/invalid token) return 401; scope failures and `authorize()` policy denials both return 403 with an identical client-visible body, distinguished only in the audit log.
25	- [ ] `profile:read:any` requests carry a `reason_code` from the closed enum (`support_ticket`, `fraud_review`, `kyc_reverification`, `legal_hold`) on every call, logged with the audit record — adding a fifth value is a documented change to this enum, not a runtime config toggle.
26	- [ ] When `api-service` calls `idp-connector` on a caller's behalf, it obtains a `connector:identity-lookup`-scoped token first, using its own `CONNECTOR_CLIENT_ID`/`CONNECTOR_CLIENT_SECRET` credential — distinct from S8's idp-connector-side handlers, which only validate that token, not issue or hold this credential.
27	
28	## Non-goals
29	
30	- No auth middleware implementation — that's S7 (LT-40), a separate pull; this story's own tests use fakes for the auth context per `decisions/test-double-strategy.md`.
31	- No real backend I/O — built against fakes, per `decisions/test-double-strategy.md`; LT-36/LT-37/LT-38 land separately.
32	- No connector-side (`idp-connector`) handler work — that's S8, which only validates the token this story's handler obtains, not the same code.
33	- No rate-limit/counter *mechanism* choice (Redis vs. in-process) — that's Renata's implementation call, per v3's own "the mechanism is your call" framing.
34	
35	## PO review script
36	
37	1. Confirm `authorize()` is called explicitly inside each handler, after parsing, before the DAO call — not registered as middleware. Read the handler code directly.
38	2. Confirm the search-response serializer and the read-response serializer are genuinely distinct code paths (grep for two separate serialization functions, not one with a masking conditional).
39	3. Confirm the pagination cursor is opaque at the API boundary (no caller-suppliable offset/page-number parameter accepted) — but don't fail the story if the handler internally passes `Offset` to the DAO; that's the correct implementation per the F-pag clarification above.
40	4. Confirm the cumulative distinct-record-touch counter's test coverage includes a `profile:read:any` case with a valid `reason_code` still hitting the cap — this is the specific regression v3 fixed, so it needs its own test, not just a `profile:search` test.
41	5. Confirm a 401/403 test pair exists asserting identical response bodies for a scope failure vs. an `authorize()` denial, distinguished only in a separate audit-log assertion.
42	6. Once S7 lands and this is deployed: a live-URL check with a real client-credentials token, confirming an actual masked search response and an actual 401 on a missing/expired token — deferred, not waived, per the Acceptance outcome above.
43	
44	## Research team review
45	
46	**Desmond Okafor — claims check:** [pending]
47	
48	**Tobias Lindqvist — objection:** [pending]
49	
50	**Naomi Voss — ruling:** [pending]
51	

{
  "command": "python3 ~/.claude/skills/profile-gen/scripts/show_profile.py --profile /Users/warrenthompson/Source/LoginID/01-product-industry-research-design/profiles/tobias-lindqvist/tobias-lindqvist.md --root /Users/warrenthompson/Source/LoginID/01-product-industry-research-design"
}

{"name": "Tobias Lindqvist", "mode": "hud", "hud": true, "badge": false, "background": false, "inline": false}

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-40.md"
}

1	# LT-40 refinement — S7: auth middleware (JWT validation)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S7 (LT-40); `02-ai-security-architecture/api-auth-design.md`, `handoff-03-auth.md` v3.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, now, and at priority
8	
9	This is the critical path per team-lead's direction: LT-39's handlers are code-review-passed but deliberately unwired (exposing them before real auth exists would serve unauthenticated PII), LT-32's issuer split is deployed and live at `/auth/token` (currently a 501 placeholder), and LT-34's live-URL story stays open until something real is reachable through auth. This story is what turns all of that into an actual, reviewable, authenticated public endpoint.
10	
11	## Correction to `backlog.md`'s own story text, found before drafting
12	
13	**S7's acceptance criterion 6 ("per-client-credential rate limits and the cumulative distinct-record-touch counter ... enforcement site: the rate-limit middleware plus its own test") is stale relative to work already merged.** `backlog.md` was written before LT-39 (PR #26) implemented `RateLimiter` and `TouchCounter` as explicit, tested checks called *inside* each handler (via a `Deps` struct), not as separate HTTP middleware — confirmed by reading `internal/api/auth.go`, `handlers.go`, `ratelimit.go`, `touchcounter.go` directly. Both are already built, both are already tested (including the two hard-deny regression tests from LT-39's own refinement), and both are already wired to whatever `AuthContext` the request context carries.
14	
15	**What this means for LT-40's actual scope:** this story does **not** rebuild rate limiting or the touch counter. Its job is narrower and already well-seamed: verify the JWT, populate `AuthContext` (via `WithAuthContext`, already exported by `internal/api`) with the token's `sub` and `scope` claims, and wire the resulting middleware into `cmd/api-service`'s router ahead of the already-built handlers. The 90-day-re-approval/lifecycle-revocation machinery (`api-auth-design.md`) and the issuer-side rate limiting (criterion 5, below) are the only genuinely new rate-limit-shaped work this story adds — the resource-API limits are already done.
16	
17	## Acceptance outcome
18	
19	"Done" for this story specifically is the first fully authenticated, live, reviewable REST endpoint: a real client-credentials token obtained from `/auth/token` (once its actual issuance logic lands — see Non-goals) or, in the interim, a token minted directly against the deployed signing key for review purposes, presented to `/profiles/search` or `/profiles/{id}` at the public URL, producing a masked search response or a 401/403/429 exactly as LT-39's tests predict.
20	
21	## Acceptance criteria (restated from `backlog.md` S7, corrected per the finding above)
22	
23	- [ ] Implements 02's token scheme without re-deriving the no-refresh/no-denylist reasoning in `api-auth-design.md` — no refresh tokens (client re-authenticates on expiry); TTL-only revocation (5–15 min), no denylist, an explicitly accepted trade-off, not to be re-litigated.
24	- [ ] Rejects any token whose `aud` doesn't match this service's audience — enforcement site: the claim-validation step, unit test with a mismatched-audience token.
25	- [ ] Verifies with the public key only; the private signing key never touches this binary's code path — enforcement site: dependency/import check, no signing-key material referenced anywhere in `internal/api` or the verifier's own binary path (this is already structurally true per LT-32's Deployment split; this criterion confirms the *code*, not just the *Deployment*, never imports signing-key material).
26	- [ ] **Pins the expected signing algorithm and rejects any token whose header claims a different one**, including `alg: none` and a symmetric-algorithm downgrade using the public key as an HMAC secret (RFC 8725 §3.1) — enforcement site: an explicit algorithm allowlist check in the JWT verification call, never left to the library's default. Unit tests: a token with `alg: none`, a token HMAC-signed using the public key bytes as the secret, both rejected.
27	- [ ] `kid`-based key rotation: the middleware selects the verification key by the token's `kid` header claim, supporting at least two concurrently valid public keys during a rotation overlap window — enforcement site: a unit test presenting tokens signed under two different `kid`s, both verifying successfully when both keys are configured.
28	- [ ] The middleware populates `internal/api.AuthContext` (via the already-exported `WithAuthContext`) with the token's `sub` and `scope` claims on success, and returns 401 (via LT-39's existing unauthorized-response path, not a new one) on any verification failure — **this is the actual integration seam with S6's work, not new response-shape design.**
29	- [ ] The token-issuing endpoint (`APP_MODE=issuer`, currently the 501 placeholder from LT-32) gets its own failed-grant rate limiting and progressive backoff per `client_id` and per source IP, separate from the resource-API limits (which are already built in `internal/api`) — with alerting on a sustained run of failed grants against one `client_id`. This is genuinely new work, not already covered by LT-39.
30	- [ ] The deadline budget for a request (context propagation into the DAO layer) is sized to cover realistic p99 DAO latency per `decisions/context-propagation.md`'s ruling — stated as a concrete number in this story's implementation, not left as "some deadline."
31	- [ ] The resource-API rate limiter and touch counter already built in LT-39 are wired to real, JWT-derived `AuthContext.Sub` values once this middleware populates them — **no new implementation, an integration check**: a live-URL test with a real token confirms the 60/10 req/min limits and the touch cap actually apply per real client identity, not per a test fake's hardcoded value.
32	
33	## Non-goals
34	
35	- **Real token issuance logic** (actually minting a signed JWT from valid client credentials at `/auth/token`) is explicitly out of scope for this story unless `backlog.md`/02 says otherwise — LT-32 only built the placeholder route and the signing-key custody; this story is the *verifier* side. Flagged as an open question below, since without it there's no way to obtain a real token for the live-URL review other than an out-of-band test token minted directly against the deployed key.
36	- No change to `internal/api`'s handler logic, masking, or error translation — that's LT-39, already merged.
37	- No change to the object-level `authorize()` policy datastore — still a stated seam (`Authorizer` interface), real implementation is a later story per `handoff-03-auth.md` v3's F8 resolution.
38	- No client-credential provisioning UI/API for new callers — out of scope for this take-home entirely, per `01-product-industry-research-design`'s track boundary.
39	
40	## Open question, flagged before hand-off rather than discovered at review time
41	
42	**Is there a real token-issuance implementation planned before or alongside this story, or does the live-URL review use an out-of-band test token?** `backlog.md` doesn't have a separate story for `/auth/token`'s actual grant logic (validate client_id/client_secret, mint a signed JWT) — LT-32 only built the route as a 501 placeholder. If issuance isn't a planned story, the PO review script below needs an out-of-band way to mint a real token against the deployed signing key for review purposes, which is a meaningfully different (and less representative) review than "call `/auth/token` for real." Flagging to Renata/team-lead now rather than discovering it when I try to run the review script.
43	
44	## PO review script
45	
46	1. Confirm the algorithm-allowlist and `kid`-rotation unit tests exist and pass — read the test names and assertions directly, not just "tests pass."
47	2. Confirm `AuthContext` population uses the already-exported `WithAuthContext`/`AuthContext` types from `internal/api`, not a parallel/duplicate type — grep for a second definition of anything auth-context-shaped.
48	3. Confirm the issuer-side rate limiting is a distinct code path from the resource-API rate limiter already in `internal/api/ratelimit.go` — this is genuinely new work, shouldn't reuse or be confused with the existing one.
49	4. Confirm the context-propagation deadline is a concrete, named number in code (e.g. a constant), not an inline magic value scattered across call sites.
50	5. Once deployed and a real (or, per the open question above, out-of-band) token is available: hit `/profiles/search` and `/profiles/{id}` at the live URL, confirming a masked response, a 401 on a missing/expired/wrong-audience token, a 403 on a wrong-scope token, and — if enough calls are made — an actual 429 once the touch cap is crossed. This is the live-URL review LT-34/LT-39 have both been waiting on.
51	
52	## Research team review
53	
54	**Desmond Okafor — claims check:** [pending]
55	
56	**Tobias Lindqvist — objection:** [pending]
57	
58	**Naomi Voss — ruling:** [pending]
59	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/04-infra-devops/refinement/postgres-in-namespace.md"
}

1	# New story refinement — deploy real Postgres in `loginid-takehome`, wire migrations, DB_DSN_FILE
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Theo Bergman (04, owner); Priya Nandakumar (05, reviewer). **Source:** gap found during LT-40 refinement — none of `04-infra-devops/backlog.md`'s existing stories (LT-45/46/47/48/49/LT-20) actually deploy a running database instance; they all assume a DB target already exists. **Jira key:** pending team-lead creating it under Epic LT-4.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering owner Theo Bergman; reviewer Priya Nandakumar.
6	
7	## Why this one, now
8	
9	LT-39's handlers are code-review-passed but there's nothing behind the DAO in the live cluster — no database, no applied schema, no seed data. This is the last missing piece before LT-34/LT-39/LT-40/LT-51's joint live-URL review can exercise a real search/retrieve call against real (if empty) data, not just an auth-and-routing check.
10	
11	## What this story is
12	
13	A single-replica PostgreSQL `StatefulSet` in the `loginid-takehome` namespace (Theo's call, confirmed: a managed instance would be disproportionate infra/cost for this take-home's scale; a single `StatefulSet` + `PersistentVolumeClaim` is the standard minimal shape and matches this project's existing "small, isolated, no HA beyond what's needed" pattern), a DB credential `Secret` provisioned out-of-band (same discipline as LT-32's JWT signing key — never through the CI-applied manifest set), a migration `Job` that runs goose against it in the correct two-invocation order before `api-service`'s rollout, and `DB_DSN_FILE` wired into `api-service`'s config so it actually connects to this database instead of erroring on an unset DSN.
14	
15	**Explicit scope limit, stated up front:** CockroachDB is exercised in CI only (LT-47's testcontainer job, against the shared `postgres`-package code path) and is **not** deployed anywhere in this cluster. Only PostgreSQL runs live. This is a deliberate scope limit for a take-home demo, not an oversight — stated here so a reviewer doesn't reasonably expect to find CockroachDB running somewhere and conclude something's missing.
16	
17	## Acceptance criteria
18	
19	- [ ] A single-replica PostgreSQL `StatefulSet` (with a `PersistentVolumeClaim` for data persistence across pod restarts) runs in `loginid-takehome`. Enforcement site: the `StatefulSet` manifest and its `Service`.
20	- [ ] The DB credential (connection string / password) is provisioned out-of-band, never through the CI-applied manifest set — matching the pattern `deploy/issuer-secret-bootstrap.yaml` already established for the JWT signing key. Enforcement site: the credential `Secret` is absent from `deploy/manifests.yaml`; a bootstrap doc/script analogous to `issuer-secret-bootstrap.yaml` documents how it's created.
21	- [ ] Per `05-data-ops/migration-approach.md` R4, the migration-runner credential (DDL rights, plus `CREATE EXTENSION pg_trgm` on Postgres specifically) and the runtime service credential (DML-only, no DDL) are two distinct `Secret`s, never one — matching LT-46's own criterion for this same split, applied here against a database that now actually exists.
22	- [ ] The migration `Job` runs goose in the **correct, corrected order**: the backend directory (`postgres/`, containing the actual `CREATE TABLE` DDL) **first**, then `shared/` (seed data only, currently just the `auth_method` "password" row) **second** — per `migration-approach.md`'s own corrected ordering (the original text had this inverted, caught reading the seed and DDL together, not caught by a green test suite that happened to apply files in a different working order). Enforcement site: the `Job`'s invocation script/command, explicitly two `goose` invocations in this order, each against its own version table (`goose_db_version_postgres`, `goose_db_version_shared`) per R4's two-independent-sequences requirement.
23	- [ ] Both goose invocations must succeed for the migration `Job` to count as successful — a partial success (backend DDL applied, `shared/` seed failed, or vice versa) is a failed `Job`, not a partial pass. Enforcement site: the `Job`'s script exits non-zero if either invocation fails.
24	- [ ] The migration `Job` runs to completion **before** `api-service`'s rollout — enforcement site: deploy pipeline ordering (readiness gate or explicit sequencing in the merge-to-main workflow), not an assumption that Kubernetes scheduling happens to land in the right order.
25	- [ ] `DB_DSN_FILE` (already a config surface `internal/config` supports per `PLANNING.md`'s Service boundaries) is wired to point at the runtime service credential's mounted file — `api-service` connects successfully on startup instead of erroring on an unset/placeholder DSN. Enforcement site: `api-service`'s Deployment manifest, mounting the runtime credential and setting `DB_DSN_FILE` to its path; a startup log line or health-check state confirming a live DB connection (not just that the env var is set).
26	- [ ] `deploy/manifests.yaml`'s header comment (which currently states "no migration Job, no DB_DSN secret — those wire up config the current code doesn't use yet") is updated to reflect that this is no longer true, so a future reader isn't misled by a stale comment.
27	- [ ] **`ResourceQuota` headroom confirmed for the new StatefulSet pod before merge** — added per Theo's own flag, given the earlier `api-service-issuer` `FailedCreate` incident from under-sized quota. Enforcement site: the quota math is shown in the PR description (current `limits.cpu`/`limits.memory` vs. the new total including Postgres's request/limit), and the `ResourceQuota` object is adjusted in the same PR if needed — not discovered as a second `FailedCreate` after merge.
28	
29	## Non-goals
30	
31	- No CockroachDB deployment — CI-only, per the explicit scope limit above.
32	- No backup/restore, replication, or HA for Postgres — single replica, single PVC, take-home scale; `migration-approach.md` explicitly leaves backup schedule/retention as 04's call and out of this document's scope, and this story doesn't add it either.
33	- No connection pooling (e.g., PgBouncer) — direct connections from `api-service` are sufficient at this scale; flag if load testing ever suggests otherwise.
34	- No change to the migration file contents themselves (DDL, seed data) — that's 05's `migration-approach.md` and the actual `.sql` files, already written; this story only runs them.
35	
36	## PO review script
37	
38	1. Confirm the `StatefulSet` and its `PersistentVolumeClaim` exist in the manifest, targeting `loginid-takehome`.
39	2. Confirm the DB credential `Secret` is absent from `deploy/manifests.yaml` and documented as provisioned out-of-band, matching the JWT-signing-key pattern.
40	3. Confirm two distinct `Secret`s exist for the migration-runner vs. runtime credentials, with different RBAC scoping (DDL-capable vs. DML-only).
41	4. Read the migration `Job`'s script directly: confirm two `goose` invocations, backend directory first, `shared/` second, each with its own `-table` flag, and that the script fails if either invocation fails.
42	5. Confirm the deploy pipeline sequences the migration `Job` to completion before `api-service`'s rollout — not merely "applied at some point."
43	6. Once deployed: confirm `api-service` actually connects (a startup log line or health-check field, not just an unset-DSN error going away), and run a real `profile:search`/`profile:read:own` call through the live URL (joint with LT-40/LT-51's review) confirming it reaches real Postgres and returns a real (even if empty) result set — this is the actual proof this story exists to provide.
44	7. Confirm the quota math was shown and the `ResourceQuota` adjusted if needed, before merge — not discovered as a `FailedCreate` after.
45	
46	## Research team review
47	
48	**Desmond Okafor — claims check:** [pending]
49	
50	**Tobias Lindqvist — objection:** [pending]
51	
52	**Naomi Voss — ruling:** [pending]
53	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-51.md"
}

1	# LT-51 refinement — real `/auth/token` grant logic
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S7a (LT-51); `02-ai-security-architecture/handoff-03-auth.md` v6 (final on JWKS path/cache guidance; v3/v4/v5 content otherwise unchanged).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, now
8	
9	PR #30 (LT-40) has already built the verifier side and the `GrantLimiter` component this story wires to — the only thing standing between the current deployment and a genuinely issued, end-to-end token is this story's actual grant logic. Once it lands, LT-34/LT-39/LT-40/LT-51 all get their joint live-URL review with a real token, per team-lead's ruling.
10	
11	## What's already built, and what this story actually adds
12	
13	**Do not rebuild these — wire to them:**
14	- `internal/api.GrantLimiter` (PR #30) — the failed-grant rate-limiting/backoff interface, keyed independently by `client_id` and source IP, with alerting on a sustained run against one `client_id`. This story constructs a real implementation instance (or reuses `InProcessGrantLimiter`) and calls `Allow`/`RecordFailure`/`RecordSuccess` around the actual grant attempt — it does not design a new backoff scheme.
15	- The JWKS endpoint (`internal/api/jwks.go` serves the client side; the issuer side serving `/.well-known/jwks.json` is this story's job, but the *shape* — RFC 7517, `kid`-keyed — is already established by what the verifier expects).
16	- `internal/api.AuthContext`/`WithAuthContext` (LT-39) and the JWT verification middleware (LT-40) — this story's only integration point with them is producing tokens whose claims those already-built and already-tested pieces correctly parse; it doesn't touch either.
17	
18	**What's genuinely new:** the `POST /auth/token` handler itself — client authentication, the client store, JWT minting, and serving JWKS at the now-fixed path.
19	
20	## Acceptance criteria (from `backlog.md` S7a, current per `handoff-03-auth.md` v6)
21	
22	- [ ] `POST /auth/token` implements RFC 6749 §4.4: `grant_type=client_credentials`, form-encoded (`application/x-www-form-urlencoded`), **not JSON** — the one endpoint in this API that follows OAuth2's own wire format rather than this project's usual JSON convention, because it's the one endpoint implementing a named OAuth2 grant. An optional `scope` parameter (space-delimited) requests a subset of the client's granted scopes; omitted means issue the full granted set.
23	- [ ] Client authentication is **HTTP Basic** (`client_id`:`client_secret` in the `Authorization` header), **not** credentials in the body — keeps the secret out of anywhere that logs request bodies more casually than headers, per RFC 6749 §2.3.1's preferred method.
24	- [ ] Errors follow RFC 6749 §5.2, **never distinguishing why in body or status**: `invalid_client` (401, `WWW-Authenticate: Basic`) for **any** client-authentication failure — an unknown `client_id` and a wrong secret for a known `client_id` return byte-identical responses. `invalid_scope` (400) if the requested scope isn't a subset of the client's granted scopes. `unsupported_grant_type` (400) for anything but `client_credentials`. Enforcement site: a test comparing the unknown-client and wrong-secret response bodies for equality, not just "both 401."
25	- [ ] Client store lives in the issuer's own datastore (per F8, not 05's schema): `client_id`, `name` (accountability — no shared credentials across a team), `client_secret_hash` (**Argon2id, same floor as `threat-model.md` Asset 1** — identical hashing discipline to password storage), `granted_scopes` (provisioned subset of `profile:read:own`/`profile:read:any`/`profile:search`/`connector:identity-lookup`), `status` (active/revoked), `created_at`, `revoked_at`. Rotation: single active secret per client (reissue generates a new one and immediately invalidates the old — no dual-secret overlap window, unlike the signing key).
26	- [ ] The token-endpoint's own brute-force protection wires to the **already-built** `GrantLimiter` (PR #30) — `Allow` checked before attempting client authentication, `RecordFailure`/`RecordSuccess` called after, keyed by both `client_id` and source IP. Enforcement site: an integration test confirming a sustained run of failed grants against one `client_id` eventually blocks further attempts and fires the alert exactly once per threshold-crossing (not once per subsequent failure) — this is `GrantLimiter`'s own tested behavior, so this test only needs to confirm the wiring, not re-test the limiter's internals.
27	- [ ] Issued JWT claims (`iss`, `aud`, `scope`, `exp`, `sub`) and the algorithm/`kid` header match exactly what LT-40's verifier middleware expects — enforcement site: an integration test that mints a token here and verifies it through the **actual** middleware from PR #30, not two independently-trusted unit tests that never touch each other.
28	- [ ] **JWKS served at the now-fixed path `/.well-known/jwks.json`** (the OIDC-discovery convention, ruled 2026-09-13 specifically so this story implements to the doc rather than the doc following already-shipped code), issuer-mode only (`APP_MODE=issuer`), reachable only in-cluster via the issuer's own `ClusterIP` `Service` — **no public `Ingress` route**, live at `AUTH_JWKS_URL=http://api-service-issuer.loginid-takehome.svc.cluster.local/.well-known/jwks.json` (already wired by Theo on the client/consuming side). Enforcement site: the route exists at that exact path and is absent from the public `Ingress`'s rules.
29	- [ ] The JWKS response may set `Cache-Control: public, max-age=<refresh interval>` as good HTTP practice, but this is **advisory only** — the verifier's own staleness policy (already built, PR #30: max staleness = 3× the refresh TTL, fail closed past that bound, per-`kid` rate-limited refetch on an unknown `kid`) is authoritative, not this endpoint's cache headers. This story does not need to coordinate cache-header values with the verifier's staleness logic; they're independent by design.
30	- [ ] **A dedicated, narrowly-scoped QA client credential is seeded in the client store, out-of-band** (same discipline as LT-32's signing-key `Secret` — never through the CI-applied manifest set), **for the PO's joint live-URL review of LT-34/LT-39/LT-40/LT-51.** Per Warren's explicit ruling (via the PM): review tooling must never mint a token by signing directly with the deployed private key — that would hand review tooling the same access F13's whole Deployment split exists to restrict to the issuer process alone. The correct mechanism is this: a real client credential, provisioned like any other caller, calling the real endpoint. Scoped to the minimum needed for the review — `profile:read:own` by default; add `profile:search` only if the review specifically needs to exercise search, going through that scope's own provisioning bar like any other caller, not a blanket grant. Enforcement site: the credential's row in the client store, its `granted_scopes` listed explicitly in the hand-off to the PO (not "whatever's convenient"), and confirmation it was created out-of-band.
31	
32	## Non-goals
33	
34	- No change to `GrantLimiter`, the JWT verification middleware, or `internal/api`'s existing handlers — all already built (PR #30/LT-39/LT-40); this story only calls into them correctly.
35	- No refresh-token support, no denylist/revocation beyond `status=revoked` at the client-store level — matches `api-auth-design.md`'s standing TTL-only-revocation design, not re-litigated here.
36	- No UI/API for self-service client provisioning — clients are provisioned directly against the datastore for this take-home's scale.
37	- No change to the resource-API's own rate limits or touch counter (LT-39) — this story's `GrantLimiter` wiring is a distinct, separate control, per the interface's own doc comment.
38	
39	## PO review script
40	
41	1. Confirm `POST /auth/token` accepts form-encoded `grant_type=client_credentials` and rejects JSON bodies (or at minimum, doesn't require JSON) — read the handler's content-type handling directly.
42	2. Confirm HTTP Basic client auth — a client presenting credentials in the request body alone (no `Authorization` header) is rejected.
43	3. Confirm the identical-body test for unknown-client vs. wrong-secret exists and passes.
44	4. Confirm `client_secret_hash` is Argon2id — read the hashing call, don't infer from a comment.
45	5. Confirm the `GrantLimiter` wiring test exists (sustained failures against one `client_id` eventually block, alert fires once per threshold-crossing).
46	6. Confirm the mint-then-verify-through-the-real-middleware integration test exists and passes.
47	7. Confirm `/.well-known/jwks.json` is live in-cluster and absent from the public `Ingress`.
48	8. Confirm the QA client credential exists, was seeded out-of-band, and its `granted_scopes` are stated explicitly (not assumed).
49	9. **The joint live-URL review, once this and LT-40 are both deployed:** obtain a real token via `POST /auth/token` using the seeded QA credential, then hit `/profiles/search` and `/profiles/{id}` at the live URL — confirming a masked response, 401/403/429 exactly as LT-39's tests predict, and (per LT-52) a real result set from the actual Postgres instance. This is the review LT-34/LT-39/LT-40/LT-51 have all been building toward; all four are accepted together in this one pass.
50	
51	## Research team review
52	
53	**Desmond Okafor — claims check:** [pending]
54	
55	**Tobias Lindqvist — objection:** [pending]
56	
57	**Naomi Voss — ruling:** [pending]
58	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-41.md"
}

1	# LT-41 refinement — S8: connector `/auth` + `/identity` (Q3)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S8 (LT-41); `02-ai-security-architecture/connector-security.md` (including its attack-tree table), `decisions/connector-token-lifecycle-redblue.md`, `handoff-03-auth.md` v6.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, now
8	
9	Q3 (the third assignment question) has no code yet, and it's genuinely independent of LT-51's in-flight work: the connector only *validates* a `connector:identity-lookup`-scoped token presented to it — it doesn't need to know how `api-service` obtains that token in the first place (that's LT-33, 02's still-open story, on `api-service`'s outbound side). Pulling this now keeps refinement from being the bottleneck while Renata and Theo build LT-51.
10	
11	**Checked the dependency graph rather than assuming:** LT-33 (02, `handoff-04-secrets.md` row 10 + `api-service`'s client credential) depends in part on "03's connector-client implementation," but that's the *outbound caller* inside `api-service`, not this story — this story is `cmd/idp-connector` itself, the inbound side. LT-41 can be built, refined, and merged without LT-33 closing first; LT-33 is what wires `api-service` to call it correctly, a separate piece.
12	
13	## Correction to `backlog.md`'s own S8 text, found before drafting
14	
15	**Two real controls from `connector-security.md`'s attack-tree table (S3 red/blue, already run and ruled) are missing from `backlog.md`'s S8 acceptance criteria entirely — not stale, just never transcribed down from the design doc into the story.** The table is the authoritative, already-ratified source; the story text predates or simply didn't carry two of its concrete requirements forward:
16	
17	1. **Leaf 1 (connection-reuse token leak):** "fresh, isolated auth header constructed per outbound request, never inherited from connection reuse" — a pooled HTTP client that doesn't reset `Authorization` per call can attach one request's token to another, even with no cache. `backlog.md`'s S8 only names `context.WithTimeout` + bounded pool + backoff from `decisions/go-layout-debate.md`; it never named this specific, checkable requirement.
18	2. **Leaf 5 (credential-stuffing oracle):** rate limiting on outbound vendor calls, keyed per calling-API-client **and** per source IP, with a stricter threshold specifically on vendor-auth **failure ratio** (not just volume — credential stuffing shows as a high failure ratio before high volume), paired with exponential backoff per identity attempted. `backlog.md`'s S8 has no rate-limiting criterion for outbound vendor calls at all.
19	
20	Both are added below as acceptance criteria, since the attack-tree table already ruled on them (Residual L on both, after blue's response) — this refinement is transcribing an already-ratified control, not inventing a new one.
21	
22	## Acceptance criteria (restated from `backlog.md` S8, plus the two additions above)
23	
24	- [ ] Implements 02's token-lifecycle spec (`connector-security.md`, `decisions/connector-token-lifecycle-redblue.md`) without re-litigating the no-cache-by-default posture.
25	- [ ] No vendor token is persisted or cached across requests by default; if a future exception is ever justified it requires re-review, not a silent default change — enforcement site: no storage/cache call in the token-fetch path.
26	- [ ] Every outbound vendor call sets `context.WithTimeout`; the outbound HTTP client uses a bounded connection pool; token-refresh retries back off rather than tight-looping — enforcement site: the HTTP client construction plus a test asserting a timeout fires.
27	- [ ] **Added (attack-tree leaf 1):** a fresh, isolated `Authorization` header is constructed per outbound vendor request — never inherited from HTTP connection/keep-alive reuse. Enforcement site: a test making two sequential vendor calls with two different presented tokens through the same pooled client, asserting the second call's outbound header matches its own token, not the first call's.
28	- [ ] **Added (attack-tree leaf 5):** outbound vendor calls are rate-limited keyed per calling-API-client identity **and** per source IP independently, with a stricter threshold on vendor-auth failure ratio specifically (not just raw volume), paired with exponential backoff per identity attempted. Enforcement site: the rate-limit/backoff component plus a test asserting a high-failure-ratio pattern trips the stricter threshold before a high-volume-but-mostly-successful pattern would.
29	- [ ] The connector's own `/auth`/`/identity` handlers validate an inbound JWT with `aud: idp-connector-service` and `scope: connector:identity-lookup`, distinct from `api-service`'s audience — enforcement site: this handler's own middleware instance, with a test asserting a `loginid-api-service`-audience token is rejected here.
30	- [ ] `/identity` accepts the vendor token as a request header (not a body field, since the assignment's fixed `{"phone","name"}` body has no credential field), fails closed with a generic error that doesn't distinguish "no token" from "bad token" from "vendor rejected it" (same user-enumeration discipline as elsewhere in this project) — per `connector-security.md`'s F3 resolution.
31	- [ ] The token variable is scoped to the narrowest function possible and never passed up the call stack beyond the vendor-call function itself — per attack-tree leaf 4's control (accepted that Go gives no guaranteed memory zeroing, but the exposure window is narrowed to one function call, not eliminated).
32	- [ ] Never logs, in any environment or error path: the end-user's vendor password, any vendor `access_token` or full `Authorization` header value, or raw vendor error response bodies (per `handoff-04-secrets.md`'s never-log list) — enforcement site: log-call review against that list, plus confirming the token field is excluded from any generic request/response dump used in panic traces or debug output, not only application logs (leaf 4's "same discipline as application logs" extension).
33	
34	## Non-goals
35	
36	- No implementation of `api-service`'s outbound call to this connector, or how `api-service` obtains its own `connector:identity-lookup` token — that's LT-33 (02, still open), a separate story.
37	- No real ABC/XYZ vendor integration — a stubbed vendor per the assignment's generic framing; this story's job is the connector's own contract and security properties, not a specific vendor's API quirks.
38	- No change to `handoff-03-auth.md`'s scope vocabulary or claim scheme — already fixed (v6).
39	- No shared rate-limit store/edge mechanism — attack-tree leaf 5 names that as 04's mechanism if enforced at a gateway; this story's own in-process rate limiting is sufficient for this take-home's scale, matching the pattern already used for `RateLimiter`/`TouchCounter`/`GrantLimiter`.
40	
41	## Flagged gap for the joint LT-34/39/40/51 live-URL review script (not this story's own scope)
42	
43	**Per team-lead's request to update the joint review script** (mint a token, create a profile via whatever write path exists, search it masked, read it full with a `reason_code`, hit the 429 cap): **checked directly — there is no write/create path anywhere in `internal/api`.** `backlog.md`'s S6 (LT-39) only implements search/retrieve (Q2's explicit scope); no `POST /profiles` handler exists, and none is currently planned as a story. The migration `Job`'s `shared/` directory only seeds the `auth_method` lookup row (per `migration-approach.md`), not `user_profile`/`user_credential` test data — there's no seeding mechanism for a reviewable profile either.
44	
45	**This is a real gap in the joint review script's own plan, not something this story can quietly work around.** Two options, neither decided here: (a) a small, explicit "seed one test profile" step — either a one-off manual `INSERT` against the deployed Postgres instance (out-of-band, like the credential bootstraps) for review purposes only, clearly not a production data-entry path, or (b) a minimal `POST /profiles` handler as a new, small story if profile creation is expected to exist at all for a complete Q1/Q2 demonstration. Flagging both to team-lead rather than picking one — this is a product/scope decision (does the submission need a write path at all?), not an engineering detail.
46	
47	## PO review script
48	
49	1. Confirm the fresh-header-per-request test (leaf 1) exists and passes.
50	2. Confirm the failure-ratio rate-limit test (leaf 5) exists and passes.
51	3. Confirm the connector's inbound middleware rejects a `loginid-api-service`-audience token (wrong audience for this service).
52	4. Confirm `/identity`'s generic failure response doesn't distinguish no-token/bad-token/vendor-rejected cases.
53	5. Read the vendor-call code path directly: confirm the token variable's scope doesn't escape the vendor-call function, and confirm no log call anywhere references the token, the vendor password, or a raw vendor error body.
54	6. Once deployed (this connector has no public route — reachable only from `api-service` via the existing `NetworkPolicy`): no direct live-URL check is possible for this story on its own; its behavior is exercised indirectly once `api-service`'s outbound call (LT-33) actually invokes it as part of the onboarding flow. Not part of the LT-34/39/40/51 joint review, which only covers Q1/Q2.
55	
56	## Research team review
57	
58	**Desmond Okafor — claims check:** [pending]
59	
60	**Tobias Lindqvist — objection:** [pending]
61	
62	**Naomi Voss — ruling:** [pending]
63	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-38.md"
}

1	# LT-38 refinement — S5: conformance suite (cross-backend behavioral conformance)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S5 (LT-38).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why pulled now
8	
9	LT-36 and LT-37's refinement (see `refinement/LT-36-LT-37.md`) cited this suite as the sole enforcement site for roughly half their own acceptance criteria and added a hard rule that neither story can be marked Done until LT-38 lands and those criteria actually pass. Pulling LT-38 now is what closes that gap — it's the next dependency in the chain (`Depends on: S3, S4`), and refining it now means it's ready to run the moment either backend PR lands, rather than sitting as a bottleneck after the fact.
10	
11	## Correction found before drafting (citation error in `backlog.md` itself, not introduced here)
12	
13	`backlog.md`'s S5 description cites "the secret-state rules (§5/§6.11)" for the `requires_secret`/`secret_state` relationship. Checked against `multi-db-strategy.md` directly: **§6.11 is item 11 in §6's numbered list — "`deletion_log` carries no PII" — a different guarantee entirely.** The `requires_secret`/`secret_state` relationship is item 12 (unlabeled with an explicit "§6.12" in the source doc's own prose, but numerically next in the same list, referred to there only as "item 12"). `is_active`'s citation as §6.10 is correct — that one checks out exactly. Fixed below by citing item 12 correctly and not repeating the backlog's §6.11 mislabel.
14	
15	## Acceptance outcome
16	
17	No public-URL surface (same as LT-35/36/37) — this is a test suite, not a deployable behavior change. "Done" means the suite exists once, runs against all three backends from one table-driven test, and every guarantee below is asserted as a specific, named test case (not a general "seems to work" pass) — modeled on the frozen-checksum-plus-structural-diff pattern Oren built for LT-35's conformance test, since 05's own §7 explicitly warns that signature conformance (LT-35) proves nothing about behavioral conformance (this story) — two implementations can match every declaration and still return different rows for the same call.
18	
19	## Acceptance criteria (restated from `backlog.md` S5, corrected and expanded)
20	
21	- [ ] The suite is written once against the `Repository` interface and executed against all three backends (postgres, cockroachdb, sqlite) from one table-driven test file, not duplicated per package. Enforcement site: a single test function parameterized over backend, not three near-identical copies.
22	- [ ] Asserts identical `Search` result sets and ordering across backends for ASCII input — this suite is `multi-db-strategy.md`'s named enforcement site for this guarantee; there is no other. Named test case: a fixed dataset seeded identically on all three backends via each backend's own `Create` (not a caller-supplied ID, since neither backend exposes that path), a fixed query, asserting identical results and order. **Rows are compared by every `ProfileQuery`-relevant field except the DAO-generated `ID`**; the suite matches corresponding rows across backends by a fixed, test-controlled non-ID field (e.g., seeded `Name` or `Phone` values guaranteed unique in the fixture set) rather than assuming identical literal `ID` values, since ID generation is backend-specific (server-side on Postgres/CockroachDB, Go-side on SQLite, per LT-36/LT-37's own acceptance criteria) and a literal row-for-row comparison including `ID` would fail on every run regardless of whether `Search` itself behaves identically.
23	- [ ] Asserts `errors.Is` sentinel parity for every condition in the §4 translation table, across all three backends — named test case per condition (not one combined test), consistent with LT-36/LT-37's "not-Done-until-LT-38" dependency: this is the specific enforcement site those stories were waiting on.
24	- [ ] Asserts the `requires_secret`/`secret_state` relationship (§6, item 12 — corrected citation, see above) as a named test: creating a credential with `secret_state = 'set'` against a method whose `requires_secret = false` returns `ErrInvalidCredential`, on all three backends.
25	- [ ] Asserts `is_active` enforcement (§6.10) as a named test: creating a credential against a deactivated `auth_method` returns `ErrInvalidMethod`, on all three backends — per the doc's own note that deactivation must not invalidate *existing* credentials, so the test also asserts an existing credential against a since-deactivated method still reads back successfully.
26	- [ ] Asserts empty-string rejection on every `*string` filter field in `ProfileQuery` — one named test case per field (`Name`, `Phone`, `Region`, `Country`), not one combined test, per the "absent, never empty" convention.
27	- [ ] Retention/deletion assertions from `multi-db-strategy.md` §7's own minimum list, each as a named test case: a zero-value `RetentionClass` (`""`) returns `ErrInvalidArgument`; `maxRows` outside `1..10_000` returns `ErrInvalidArgument`; `OldestSurvivingAt` is non-nil when rows remain (including when nothing was old enough to delete) and nil only when the class is empty; `Drained` is false while deletable rows remain at the batch limit and true on the final batch; every delete writes exactly one `deletion_log` row in the same transaction with the reason code the method itself asserts; an already-cancelled context returns before deleting anything; `deletion_log` carries no PII-shaped column (§6.11 — correctly cited here, this is the actual §6.11 guarantee).
28	- [ ] The CockroachDB-specific retry path is exercised for real: at least one test forces a genuine SQLSTATE `40001` (e.g. two concurrent transactions racing on the same row) against a real CockroachDB instance/testcontainer and asserts the operation succeeds after retry, not a mocked retry.
29	- [ ] CI (04's pipeline) runs this suite against every backend including CockroachDB, not just Postgres+SQLite — flagged to 04 if their pipeline configuration doesn't do this; enforcement site is the CI job matrix/config itself, not this suite's own code.
30	- [ ] Following the model Oren built for LT-35: the suite's test data / expected-behavior assertions state, in a comment, which parts are derived directly from `multi-db-strategy.md`'s prose (the guarantees list in §7 and the numbered items in §6) and, where practical, carry the same frozen-copy-plus-checksum protection so a later revision to those sections forces a human re-check rather than the suite silently asserting a stale guarantee. Scoped down from LT-35's version since this suite asserts *behavior*, not *signatures* — a full checksum-gated transcription may not be practical for prose guarantees the way it was for Go signatures: LT-35's checksum worked because §1–§4 is one contiguous block, hashed once, while this suite's guarantees are scattered across §4, §6 (items 10/12), §7, and §3c — non-contiguous fragments that would each need a separately-pinned hash boundary, fragile to unrelated prose edits nearby. At minimum, each test case's doc comment names the specific `multi-db-strategy.md` line/item it enforces, so a future doc change is at least greppable.
31	
32	## Non-goals
33	
34	- No new backend implementation — this story only tests LT-36/LT-37's output.
35	- No handler/API-layer testing — that's LT-39 and later, against fakes per `decisions/test-double-strategy.md`, not this suite.
36	- No performance/load testing — "identical" here means identical correctness (rows, order, errors), not identical latency; SQLite's full-table-scan search is explicitly *not* required to be as fast as Postgres's indexed search, only as correct.
37	
38	## PO review script
39	
40	1. Confirm the suite is one table-driven test executed against all three backends, not three copies (read the test file structure).
41	2. Confirm each guarantee above has its own named test case (grep test names against the list) — not one broad "conformance" test that silently covers several guarantees and can't tell you which one failed.
42	3. Confirm the CockroachDB retry test forces a real `40001` against a real CockroachDB instance, not a mock — read the test setup.
43	4. Confirm CI's job matrix actually includes CockroachDB as a target, not just Postgres+SQLite (04's pipeline config, once it exists).
44	5. Once LT-36 and LT-37 are both implemented and this suite runs against them: confirm it's actually green on all three backends, and go back and mark the LT-38-dependent criteria in LT-36/LT-37's refinement doc as accepted, updating both stories out of "implemented, verification pending LT-38" status.
45	
46	## Research team review
47	
48	**Desmond Okafor — claims check:** Independently re-verified my §6 citation correction — confirmed correct (item 10 = `is_active`, item 11 = deletion_log-no-PII, item 12 = requires_secret/secret_state). Noted 05's own §7 summary under-cites item 12 but confirmed LT-38's criteria correctly test both items 10 and 12 regardless, which is more complete than a literal restatement of §7 would be — not a defect. Retention/deletion list checked word-for-word against §7's minimum list, exact match. Confirmed the "no other enforcement site" claim for Search ordering tracks 05's own framing, not overreach. Confirmed the frozen-checksum hedge was appropriately tentative, not overreach, and supplied a concrete technical reason (§1–§4 is one contiguous block vs. this suite's guarantees being scattered across non-contiguous sections) — added to the doc.
49	
50	**Tobias Lindqvist — objection:** The Search-parity criterion's "identical result sets" didn't say how rows are matched across backends given that each backend generates its own `ID` independently (server-side on Postgres/CockroachDB, Go-side on SQLite) — a literal row-for-row comparison including `ID` would fail every time regardless of whether `Search` behaves correctly, and whoever wrote the test would have had to invent an interpretation nobody downstream could see without reading the source. Counter-proposal accepted: rows are now explicitly compared by every `ProfileQuery`-relevant field except `ID`, matched across backends by a fixed non-ID field from the seeded fixture set.
51	
52	**Naomi Voss — ruling:** Both fixes applied (the citation correction independently confirmed; the ID-matching ambiguity closed). This refinement is accepted and ready to hand off. This is the third LT-3x pair in a row where the research team caught a real, specific ambiguity that would otherwise have been decided unilaterally and invisibly by whoever wrote the test first — the pattern is doing exactly what it's for.
53	
54	## PO acceptance review — CI status, joint pass 2026-09-13
55	
56	**Reviewer:** Naomi Voss (PO). Checked `internal/dao/conformance/testutil_test.go` and the live `pr-check.yml` on `main` directly, not the "Build, lint, test" job's green status alone.
57	
58	**Finding: the CI acceptance criterion is not met, and "Build, lint, test" going green does not mean what it appears to mean.** `newPostgresFamilyFixture` (shared by the `postgres` and `cockroachdb` backends) explicitly skips (`t.Skipf`) when its DSN env var (`TEST_POSTGRES_DSN`/`TEST_COCKROACHDB_DSN`) isn't set — by its own comment, "this suite asserts behavior, it doesn't stand up infrastructure." `pr-check.yml` never sets either variable and never provisions a Postgres/CockroachDB service or testcontainer. Only the SQLite fixture is genuinely self-contained (in-memory). **Net effect: every Postgres and CockroachDB conformance test — including `TestConformance_CockroachDB_RealSerializationRetry`, this story's own flagship acceptance criterion — silently skips on every CI run, and Go reports a skip as neither pass nor fail, so nothing currently flags this as a problem.** `go test ./... -race` returning success proves SQLite's conformance tests passed; it proves nothing about the other two backends.
59	
60	**Ruling (team-lead):** the suite itself is well-built and correctly scoped — this is a pipeline-wiring gap, not a defect in the tests. Fix in flight: Theo adds real Postgres/CockroachDB service containers to `pr-check.yml`; Renata makes the fixtures fail loudly under `CI=true` rather than skip, so a future regression of this exact gap can't hide behind a green build again.
61	
62	**Verdict: LT-38 FAILS criterion "CI runs every backend including CockroachDB" — fix in flight, not accepted yet.** Every other behavioral criterion is scored as verified, from two independent sources: Renata's real-backend test runs (once the fixtures are wired for real) plus this joint review's own live checks against the actual deployed Postgres instance (masking, full reads, scope separation — recorded in `refinement/LT-36-LT-37.md` and `LT-39.md`). Not a blanket fail on the suite's substance — narrowly, honestly, a fail on the one criterion that was silently unmet.
63	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-39.md"
}

1	# LT-39 refinement — S6: REST handlers for search/retrieve user_profile (Q2)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S6 (LT-39); `02-ai-security-architecture/handoff-03-auth.md` v3.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one now
8	
9	LT-32 (issuer Deployment split) is refined and handed off, unblocking S7 (auth middleware, LT-40), which this story sits alongside. LT-39 itself formally depends only on S2 (merged) and 02's accepted hand-off — it doesn't block on LT-32/S7 in `backlog.md`'s own dependency graph, and its handlers can be built and merged against fakes right now, per `decisions/test-double-strategy.md`. Refining it now means it's ready the moment S7 lands, rather than sitting as the next bottleneck after that.
10	
11	## Acceptance outcome
12	
13	This is the first story that adds real, caller-visible REST behavior — not just a skeleton. But it depends on S7 (auth middleware) to be *truly* reviewable at the public URL with a real token; until S7 lands, "done" for this story specifically means: handlers implemented and tested against fakes, all criteria below satisfied in code and unit tests, with the actual live-URL, real-token exercise deferred to whenever S7 merges (same "verification pending" pattern as LT-36/LT-37 waiting on LT-38 — not waived, just sequenced).
14	
15	## Acceptance criteria (restated from `backlog.md` S6, cross-checked against `handoff-03-auth.md` v3)
16	
17	- [ ] Implements `handoff-03-auth.md` v3's scope vocabulary (`profile:read:own`, `profile:read:any`, `profile:search`) and pagination/rate-limit numbers without re-deriving 02's authz-scoping reasoning.
18	- [ ] `authorize(sub, scope, target)` runs as an explicit call inside each handler after request parsing, before the DAO call — not a second middleware, per v3's confirmed placement (it needs the parsed target id, which pre-routing middleware doesn't have). `authorize()` checks `caller_referral`/caller-role data against the token-issuer's own datastore, **not against 05's schema** — 05 was never assigned that table.
19	- [ ] `profile:search` responses carry masked PII fields by default (phone as `***-***-1234`, address reduced to `locality`/`region` only). Unmasked detail requires a separate, separately-audited follow-up call under `profile:read:own` or `profile:read:any` against the specific record id — **this reuses the existing scopes, it does not invent a fourth "expand" flag**; masking is a `profile:search`-response property, not a per-call parameter. Enforcement site: the search-response serialization path is a distinct code path from the read-response one, not the same serializer with a masking flag.
20	- [ ] **Pagination — clarified per v3's F-pag correction, since `backlog.md`'s original wording could be misread by an implementer:** the API-facing cursor is opaque to the caller — callers cannot construct or walk one by hand — but it may (and in the simplest correct implementation, does) encode the DAO's own `Offset` directly underneath. "Cursor-based pagination only" means **the caller-facing contract is opaque-cursor-only, not that the handler is forbidden from using the DAO's `Offset` field internally.** The actual anti-enumeration control is the cumulative distinct-record-touch counter (next bullet), not the cursor mechanism itself. Default page size 20, hard ceiling 50, enforced in the handler before the DAO is ever called — the DAO's own `Limit` bound (1..100, default 50) is a second, independent backstop only reachable if the handler clamp is bypassed, not a second policy a caller can rely on.
21	- [ ] A cumulative distinct-record-touch counter per caller per rolling 24h window is enforced, independent of per-minute rate limits, applying to **both** `profile:search` and `profile:read:any` unconditionally — a valid `reason_code` on `read:any` satisfies the per-call `authorize()` check but does **not** exempt the caller from this cumulative cap (v3's explicit fix to an earlier wording that made the counter a no-op for `read:any`). Enforcement site: a counting store incremented once per distinct record id returned, checked before the response is sent.
22	- [ ] **Resolved by 02's ruling (raised by Tobias's objection, routed to Marcus):** crossing the cumulative counter's threshold **hard-denies** (429) every subsequent `profile:search`/`profile:read:any` call from that caller for the remainder of the rolling 24h window — distinct from the 401/403 pair — **in addition to** alerting, not instead of it. An alert-only reading would make the counter detection rather than a control, recreating the "attribution stands in for volume control" gap 01's S4 objection closed at the product-requirements level. `handoff-03-auth.md` and `api-auth-design.md` updated with this explicit ruling. Enforcement site: the counting store's threshold check gates the request before it's served, returning 429; a separate alert fires regardless of whether the request was already being denied.
23	- [ ] A search request with no filter field at all is rejected by this handler with a 400 before it reaches the DAO — the DAO itself treats an all-nil `ProfileQuery` as legal, so this handler-layer rejection is the only enforcement site for "no bare unconstrained search."
24	- [ ] A `profile:search` query rejected for exceeding the result cap unconstrained (e.g. a bare wildcard) is rejected outright, not truncated — enforcement site: the same in-handler call site, checked before the query is built.
25	- [ ] Unmapped DAO errors never surface `err.Error()` to the client; only the mapped sentinels' safe messages do — per `decisions/error-semantics.md`'s boundary translation function. Authn failures (missing/invalid token) return 401; scope failures and `authorize()` policy denials both return 403 with an identical client-visible body, distinguished only in the audit log.
26	- [ ] `profile:read:any` requests carry a `reason_code` from the closed enum (`support_ticket`, `fraud_review`, `kyc_reverification`, `legal_hold`) on every call, logged with the audit record — adding a fifth value is a documented change to this enum, not a runtime config toggle.
27	- [ ] When `api-service` calls `idp-connector` on a caller's behalf, it obtains a `connector:identity-lookup`-scoped token first, using its own `CONNECTOR_CLIENT_ID`/`CONNECTOR_CLIENT_SECRET` credential — distinct from S8's idp-connector-side handlers, which only validate that token, not issue or hold this credential.
28	
29	## Non-goals
30	
31	- No auth middleware implementation — that's S7 (LT-40), a separate pull; this story's own tests use fakes for the auth context per `decisions/test-double-strategy.md`.
32	- No real backend I/O — built against fakes, per `decisions/test-double-strategy.md`; LT-36/LT-37/LT-38 land separately.
33	- No connector-side (`idp-connector`) handler work — that's S8, which only validates the token this story's handler obtains, not the same code.
34	- No rate-limit/counter *mechanism* choice (Redis vs. in-process) — that's Renata's implementation call, per v3's own "the mechanism is your call" framing.
35	
36	## PO review script
37	
38	1. Confirm `authorize()` is called explicitly inside each handler, after parsing, before the DAO call — not registered as middleware. Read the handler code directly.
39	2. Confirm the search-response serializer and the read-response serializer are genuinely distinct code paths (grep for two separate serialization functions, not one with a masking conditional).
40	3. Confirm the pagination cursor is opaque at the API boundary (no caller-suppliable offset/page-number parameter accepted) — but don't fail the story if the handler internally passes `Offset` to the DAO; that's the correct implementation per the F-pag clarification above.
41	4. Confirm the cumulative distinct-record-touch counter's test coverage includes a `profile:read:any` case with a valid `reason_code` still hitting the cap — this is the specific regression v3 fixed, so it needs its own test, not just a `profile:search` test.
42	4a. Confirm a test exists asserting that a call made **after** the threshold is crossed returns 429 and is not served — not merely that the counter's value is observed to exceed the threshold — per 02's hard-deny ruling.
43	5. Confirm a 401/403 test pair exists asserting identical response bodies for a scope failure vs. an `authorize()` denial, distinguished only in a separate audit-log assertion.
44	6. Once S7 lands and this is deployed: a live-URL check with a real client-credentials token, confirming an actual masked search response and an actual 401 on a missing/expired token — deferred, not waived, per the Acceptance outcome above.
45	
46	## Research team review
47	
48	**Desmond Okafor — claims check:** Verified the F-pag reading (opaque-at-the-boundary, not never-use-Offset-internally) word-for-word against v3. Verified the read-any/reason_code/cumulative-counter interaction, `authorize()` placement, caller_referral/F8 resolution, masked-response/F6 framing (confirmed as a near-verbatim quote, not editorializing), all-nil-search/F10, and bare-wildcard/F52 handling all match v3 exactly. Confirmed the reason_code enum values are a legitimate, sourced enrichment over backlog.md's vaguer original, not staleness. No corrections needed — cleanest refinement checked so far.
49	
50	**Tobias Lindqvist — objection:** The cumulative counter's "alerts on threshold, not just hard-blocks" wording doesn't clearly require denying the caller's subsequent requests once the threshold is crossed — as written, a caller over-cap could keep issuing served calls indefinitely with only an alert firing, recreating the "attribution stands in for volume control" gap his own S4 objection closed at the product-requirements level. Checked against the source: the ambiguity is genuinely in `handoff-03-auth.md` v3 itself, not a transcription error in this refinement — so this is 02's mechanism decision, not mine to invent. Routed to Marcus with Tobias's argument; the criterion is marked PENDING in the doc with his exact proposed wording ready to drop in if 02 confirms hard-deny.
51	
52	**Naomi Voss — ruling:** This refinement is accepted and ready to hand off in full. Marcus has since ruled on the pending item: crossing the cumulative counter's threshold hard-denies (429) subsequent calls, alerting in addition to, not instead of, the denial — exactly the outcome Tobias argued for. Updated above with his exact ruling and a matching PO-script step (4a). Every criterion is now resolved; nothing remains pending.
53	
54	## PO acceptance review — PR #26
55	
56	**Reviewer:** Naomi Voss (PO). **Date:** 2026-09-13. **PR:** `https://github.com/wtvamp/loginid-takehome/pull/26`.
57	
58	Pulled the PR and ran `go build ./... && go test ./internal/api/... -v` myself — all 25 tests pass, not taking the PR description's claim on faith. Confirmed by name and content, not just by count:
59	
60	- `TestSearchHandler_TouchCapExceeded_429NotServed` and `TestGetProfileHandler_ReadAny_ValidReasonCodeStillHitsTouchCap` — both regression tests from this refinement's PO-script items 4/4a exist and pass, asserting an actual 429 HTTP response and that the underlying handler (`Search`/`Get`) is never called once denied — not merely that a counter value is observed to exceed threshold.
61	- `TestGetProfileHandler_ScopeFailureAndAuthorizeDenial_IdenticalBody` — F7's identical-body requirement, present and passing.
62	- `TestCursor_OpaqueAtAPIBoundary` — confirms the cursor is opaque at the boundary while the DAO's `Offset` is used internally, matching the F-pag clarification exactly.
63	- `TestSearchHandler_ResponseIsMasked`, `TestSearchHandler_EmptyBody_400`, `TestSearchHandler_PageSizeAboveCap_RejectedNotTruncated`, `TestSearchHandler_DAOError_NeverLeaksRawMessage` — all present and passing, covering the masking, empty-search-rejection, cap-rejection, and error-sanitization criteria.
64	- `authorize()` is called explicitly inside `handlers.go`, not registered as middleware — confirmed by reading the handler code directly, not inferred from the PR description.
65	
66	**Correctly not wired into the live router yet** — the PR's own reasoning (exposing unauthenticated PII before S7's middleware exists would defeat the purpose of this story's own authz work) matches this refinement's "Acceptance outcome" section exactly.
67	
68	**Verdict: code review pass, URL review pending.** Per team-lead's correction — this is a code-level pass, not the story's Done bar; LT-39 goes In Test at merge and stays there until S7 (LT-40) wires auth and the handlers are reachable at the public URL, where the actual behavior (429 after the cap, masked search body, 401/403) gets reviewed live. Also still pending: Oren/Nolan's and 02's cold-reviewer passes on PR #26, separate from this code review. Not marking Done until all of that closes.
69	
70	**Superseded in part — Ingrid's cold review found a real defect my pass missed.** My code review above was run against PR #26 as it stood at the time, and I did not check for audit-log emission specifically — Ingrid's cold review found no audit-log emission anywhere in the PR despite this story's own acceptance criteria requiring it (`reason_code` logged with the audit record on `profile:read:any`; a scope failure vs. an `authorize()` denial distinguished only in the audit log, per F7). Correctly ruled an unmet criterion, not a nitpick — Renata is adding an `AuditLogger` interface, a fake, and tests before merge, plus rejecting an explicit `offset` query parameter (a gap my own pass also didn't catch). My "code review pass" verdict above predates this fix and did not itself verify audit-log behavior; re-checking once Renata pushes the update, before this goes back to In Test.
71	
72	## PO acceptance review — joint live-URL pass, 2026-09-13
73	
74	**Reviewer:** Naomi Voss (PO). Minted real tokens for all three scopes (search, read:own, read:any) using the seeded QA client credentials, fetched directly via `kubectl -n loginid-takehome get secret qa-client-credential` and never pasted anywhere. Against the live URL with the seeded demo profiles:
75	
76	- `POST /profiles/search` with the search token — 200, masked results (`***-***-####`, region-only), all three seeded profiles returned. **Confirmed.**
77	- `GET /profiles/{id}` with the read:own token on its allowed profile — 200, full record. On a different profile — **403**. **Confirmed.**
78	- `GET /profiles/{id}` with the search token (wrong scope) — **403, byte-identical body to the read:own-on-wrong-profile 403 above** — F7's identical-body requirement confirmed live, not just by unit test. **Confirmed.**
79	- `GET /profiles/{id}` with the read:any token, no `reason_code` — 400. With an invalid `reason_code` — 400, same message. With a valid one (`support_ticket`) — 200, full record. **Confirmed.**
80	- No token — 401. **Confirmed.**
81	
82	**Real defect found and reproduced live, not from code alone: the per-minute `RateLimiter` (10 req/min search) does not reliably enforce its stated limit.** `api-service` runs 2 replicas; `RateLimiter` is in-process (per-pod memory) — its own code comment states this is "a deliberate simplification, not hidden — a production multi-instance deployment would need a shared store (Redis) instead," but the deployed manifest runs 2 replicas anyway. Reproduced: a 12-call rapid burst produced zero 429s (load-balanced roughly evenly across both pods, each staying under its own independent count of 10); a subsequent 30-call burst started producing 429s at call 9, at a point with no fixed relationship to the stated "10 req/min." The effective limit is somewhere between 10–20 depending on load-balancer distribution, not a real per-client cap. `TouchCounter` and `GrantLimiter` share the identical in-process, per-pod design (confirmed by reading their source) and almost certainly have the same gap, though I could not exercise `TouchCounter`'s cap live — see below.
83	
84	**`TouchCounter`'s 2000-distinct-record cap is not exercisable at all with the current demo dataset** — only 3 profiles are seeded (`deploy/demo-data/001-review-profiles.sql`), nowhere near the threshold. This is a limitation of the review environment, not a defect, but it means this specific criterion is unverified live either way.
85	
86	**Ruling (team-lead):** `api-service` moves from 2 replicas to 1 (matching the issuer Deployment's own replica count) — a security control beats nominal HA for a POC at this scale; Redis remains the documented production-scale path (already stated in the code's own comments), not something to build now. Re-run the rate-limit burst test after Theo's manifest PR redeploys.
87	
88	**Verdict, per-criterion, scored honestly rather than rounded to a single pass/fail:**
89	- Masking, scope separation (own/any/search), F7's identical-body requirement, `reason_code` closed-enum enforcement, unauthorized/negative paths — **live-verified, pass.**
90	- Per-minute `RateLimiter` (10 req/min search / 60 req/min read) — **verified by unit test only; live verification pending the replica fix.** The reproduced cross-replica gap above is real and was live, but it's a deployment-topology defect the replica-count ruling addresses, not a defect in the limiter's own logic (which the unit tests already correctly cover for a single instance).
91	- `TouchCounter`'s 2000-distinct-record cap — **verified by unit test (LT-39's own tests) only, not live; live exercise would need ≥2000 synthetic rows, deliberately not seeded for this review.** Stated plainly rather than claimed as something this review actually exercised.
92	
93	This story's search/read/auth-integration behavior is solid and live-confirmed; the two rate-limit-shaped criteria are honestly scored as test-verified-not-live-verified for stated, specific reasons, not silently passed.
94	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-42.md"
}

1	# LT-42 refinement — S9: handler and connector unit tests
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S9 (LT-42); `decisions/test-double-strategy.md`.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this shape, not a from-scratch build
8	
9	**Checked before drafting: most of this story's scope already exists**, built incrementally as part of LT-39/LT-40/LT-41/LT-51's own PRs, not deferred to a dedicated later story the way `backlog.md`'s original sequencing (S9 depends on S6, S7, S8) implied. Confirmed by listing the actual test files: `internal/api` has `handlers_test.go`, `jwtmiddleware_test.go`, `ratelimit_test.go`, `touchcounter_test.go`, `grantlimiter_test.go`, `tokenhandler_test.go`, `jwks_test.go`, `masking_test.go`, `cursor_test.go`, `stopgap_authorizer_test.go`, `fakes_test.go`, `clientstore_test.go`, `issuer_verifier_integration_test.go`; `internal/connector` has `handlers_test.go`, `httpvendorclient_test.go`, `identitylimiter_test.go`, `stubvendorclient_test.go`. This story's actual remaining job is **verification of completeness against its own stated criteria, plus closing any real gaps found** — not building a test suite that's already substantially written.
10	
11	## Acceptance criteria (restated from `backlog.md` S9, reframed as a completeness check)
12	
13	- [ ] **Hand-written fakes, not generated mocks** — confirmed already true: `internal/api/fakes_test.go` exists as hand-written interface fakes per `decisions/test-double-strategy.md`'s ruling; no `gomock`/`mockery` dependency anywhere in `go.mod`. Verify this remains true, not re-decide it.
14	- [ ] **Same-PR fake-update discipline** — `decisions/test-double-strategy.md` states this as a *review checklist item*, not an automated check. This story's job: confirm the checklist item is actually stated somewhere a reviewer will see it (PR template, `CONTRIBUTING`, or the decision doc itself, cross-referenced) — not just asserted in a design doc nobody re-reads at review time.
15	- [ ] Handler tests cover every sentinel-to-HTTP-status mapping from `decisions/error-semantics.md`'s boundary translation function, **including the unmapped-error-defaults-to-500-with-no-detail case** — confirm this specific case has its own named test (`TestSearchHandler_DAOError_NeverLeaksRawMessage`, already found in `handlers_test.go` during LT-39's review — re-confirm it covers the *unmapped* case specifically, not only the mapped-sentinel cases).
16	- [ ] Connector tests cover the no-cache token-lifecycle assertion (a second `/identity` call re-fetches via `/auth`, never reuses a prior token) — confirm this exact assertion exists in `internal/connector`'s test files, since it's the one criterion from `backlog.md`'s original S9 text I have not yet independently confirmed is covered by name.
17	- [ ] **Gap check, not assumed clean:** read every test file listed above for the *specific* named assertions this story's criteria require, not just "tests exist." A file existing doesn't mean the specific criterion is covered — the LT-39/LT-40 reviews already found real gaps (audit logging, timing-oracle) in code that had substantial test coverage but missed a specific requirement.
18	
19	## Non-goals
20	
21	- No new handler/connector logic — this story is tests only, confirming and closing gaps in what's already built.
22	- The DAO's own cross-backend correctness — that's LT-38's job, already its own story with its own (currently failing) CI criterion, not duplicated here.
23	- No change to `decisions/test-double-strategy.md` itself unless a real gap in its own stated discipline is found.
24	
25	## PO review script
26	
27	1. Confirm no generated-mock library is a dependency (`go.mod`), and that `fakes_test.go` (or equivalent) contains genuinely hand-written fakes.
28	2. Confirm the same-PR fake-update rule is stated somewhere a reviewer actually sees at review time (not buried only in a decision doc).
29	3. Read `handlers_test.go`'s DAO-error test directly: confirm it specifically exercises an *unmapped* sentinel (one not in the seven-sentinel translation table) and asserts a generic 500 with no wrapped detail — not only the mapped-sentinel cases.
30	4. Read `internal/connector`'s test files for the specific no-cache-reuse assertion: two sequential `/identity` calls, second one re-fetching via `/auth`, asserted via a mock HTTP client call-count or distinct-token check — not just "no persistent storage exists" inferred from the absence of a cache field.
31	5. Report any gap found as a fix, not a new story — this is meant to close S9 in one pass given how much is already built.
32	
33	## Research team review
34	
35	**Desmond Okafor — claims check:** [pending]
36	
37	**Tobias Lindqvist — objection:** [pending]
38	
39	**Naomi Voss — ruling:** [pending]
40	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-33.md"
}

1	# LT-33 refinement — wire `api-service`'s client credential to call the connector, and the vendor-token pass-through
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `02-ai-security-architecture/backlog.md` S13 (LT-33) — a 02-authored story whose implementation is 03's code, refined here since it's engineering work, same pattern as LT-51.
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, now
8	
9	Per team-lead: this is the only story that makes Q2 and Q3 one system — everything up to now proves `api-service`'s own REST surface (Q2) and `idp-connector`'s own inbound contract (Q3) work in isolation, but nothing yet has `api-service` actually call the connector as part of a real flow. It has a real security surface (a client credential `api-service` itself must hold and use correctly), which is why 02 authored the story even though 03 writes the code.
10	
11	**Checked before drafting: this is genuinely greenfield.** `grep`'d `internal/api` and `cmd/api-service` for any existing connector-calling code — only the `ScopeConnectorIdentityLookup` constant exists (used by the connector's own inbound-audience check, already built and tested in LT-41). No outbound client, no onboarding-flow handler, nothing in `api-service` mints or uses a `connector:identity-lookup` token today.
12	
13	## What this story actually is
14	
15	Two related gaps `connector-security.md` and `handoff-04-secrets.md` already resolved at the design level; this story is the implementation:
16	
17	1. **`api-service` needs its own client credential** (row 10 of `handoff-04-secrets.md`) to authenticate to the connector's inbound auth in the first place — the same `POST /auth/token` mechanism LT-51 built, but `api-service` is itself a *client* of that endpoint here, not the resource server.
18	2. **The vendor-token pass-through** (`connector-security.md` F3): our own `/auth` returns the vendor's `access_token` to the authenticated internal caller (`api-service`, on the onboarding flow's behalf); `api-service` holds it only for the span between that call and the following `/identity` call, then presents it as a request header (`X-Vendor-Access-Token`, confirmed by name in LT-41's implementation) — never in the body, never persisted, never logged.
19	
20	## Acceptance criteria (from `handoff-04-secrets.md`/`connector-security.md`, restated for implementation)
21	
22	- [ ] `api-service` obtains a `connector:identity-lookup`-scoped token from `/auth/token` using its own client credential (`CONNECTOR_CLIENT_ID`/`CONNECTOR_CLIENT_SECRET`, per `PLANNING.md`'s config surface — already named there, never implemented) before calling `idp-connector`'s `/auth` or `/identity`.
23	- [ ] The onboarding flow's vendor-auth step (whatever handler mediates the two-screen flow `ux-notes.md` describes) receives the vendor `access_token` from our `/auth` response and holds it **only** for the span between that call and the following `/identity` call — enforcement site: the handler/service layer that mediates this, not the connector (which stays stateless, per LT-41). No storage, no cache, scoped to the narrowest function possible — same discipline `connector-security.md`'s attack-tree leaf 4 already requires on the connector's own side, applied symmetrically here since `api-service` now holds the same class of secret for the same short window.
24	- [ ] `/identity` is called with the vendor token as a request header (`X-Vendor-Access-Token`, matching LT-41's already-built expectation), never a body field.
25	- [ ] `api-service`'s own `connector:identity-lookup` token (distinct from the vendor token) is obtained fresh per onboarding flow, not cached/reused across unrelated flows — matching the no-refresh-token design already standing for every other client credential in this project (`api-auth-design.md`).
26	- [ ] Never logs, in any environment or error path: the vendor password, the vendor `access_token`, `api-service`'s own `CONNECTOR_CLIENT_SECRET`, or any full `Authorization`/`X-Vendor-Access-Token` header value — per `handoff-04-secrets.md`'s never-log list, same standard already enforced on the connector's own side (LT-41).
27	- [ ] `01-product-industry-research-design/ux-notes.md`'s two-screen flow description and this mechanism agree on what the frontend/onboarding-mediating layer actually holds between screens — checked directly: `ux-notes.md:27` already states the token is "held only by this onboarding flow, only for the span between the two calls, and is never persisted past this signup step" (added per Marcus's exact sentence during the earlier consistency-pass fix) — this criterion is **already satisfied by the existing doc**, no coordination needed unless the actual implementation ends up diverging from that description.
28	
29	## Non-goals
30	
31	- No change to `idp-connector`'s own inbound handlers — already built and tested (LT-41); this story only calls them correctly from the other side.
32	- No change to the token-issuance mechanism itself — `/auth/token` already exists (LT-51); `api-service` is a new *caller* of it, not a change to how it works.
33	- No real vendor UI/frontend — the "onboarding flow" here is `api-service`'s own handler/service-layer mediation, not a client-facing UI (out of scope for this backend-focused assignment, per `01-product-industry-research-design`'s track boundary).
34	- No new client-provisioning UI — `api-service`'s own connector-calling credential is provisioned the same out-of-band way as every other credential in this project (QA clients, signing key, DB credentials).
35	
36	## PO review script
37	
38	1. Confirm `api-service` genuinely obtains a fresh `connector:identity-lookup` token per onboarding flow (not a package-level cached client) — read the code directly.
39	2. Confirm the vendor token's variable scope doesn't escape the mediating handler function — same check applied to the connector's own code in LT-41.
40	3. Confirm `/identity` is called with the header, not the body — a test asserting the outbound request shape.
41	4. Confirm no log call anywhere references the vendor token, vendor password, or `CONNECTOR_CLIENT_SECRET` — log-call review against the never-log list.
42	5. Once deployed: this is testable end-to-end only via the actual onboarding flow, which isn't a public-URL-exposed endpoint on its own (no assignment question asks for one) — acceptance is code-review plus a unit/integration test exercising the mediating handler against a fake connector client, not a live-URL check.
43	
44	## Research team review
45	
46	**Desmond Okafor — claims check:** [pending]
47	
48	**Tobias Lindqvist — objection:** [pending]
49	
50	**Naomi Voss — ruling:** [pending]
51	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-43.md"
}

1	# LT-43 refinement — S10: README (implemented vs. stubbed, AI workflow, test strategy)
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03). **Source:** `03-engineering-delivery/backlog.md` S10 (LT-43).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist; engineering counterpart Renata Cole.
6	
7	## Why this one, why it matters more than most
8	
9	Per team-lead: this is the document LoginID reads first — the submission's front door — and it should be written by someone who watched the process, not generated at the end from a summary of a summary. Depends on S1–S9, all of which are now Done or in their final pass, so this is genuinely ready to write for real, not from a plan.
10	
11	## What "implemented vs. stubbed" actually is, checked directly rather than assumed
12	
13	**Real, live, deployed:**
14	- Full DAO layer against real Postgres (LT-35/36/38 — all Done, verified live against the deployed database and in CI against real Postgres/CockroachDB service containers).
15	- REST search/retrieve handlers (LT-39 — Done), auth middleware (LT-40), real token issuance (LT-51 — refined, in progress), all verified live at `https://loginid-takehome.uplifttech.org` with real minted tokens.
16	- The connector's own inbound `/auth`/`/identity` contract (LT-41 — Done, verified in-cluster via port-forward with a real vendor stub backing it).
17	- CI/CD (LT-47), containerization (LT-45), secrets delivery (LT-46), database provisioning (LT-52) — all Done, deployed, live.
18	
19	**Deliberately stubbed, and why — this is the section a cold reader needs, stated plainly, not left to infer:**
20	- **The third-party vendor (ABC/XYZ) is an in-process `StubVendorClient`**, not a real HTTP integration — `idp-connector` falls back to it when `IDP_ABC_BASE_URL` is unset, logs this explicitly on startup, and this is `backlog.md`'s own stated non-goal for LT-41 ("no real vendor integration"). The assignment names the vendor generically; a real integration was never in scope.
21	- **The `authorize()` object-level policy hook is a `StopgapAuthorizer`**, not the real caller-referral datastore `handoff-03-auth.md`'s F8 resolution describes — a stated seam, not a hidden gap, per LT-39/LT-40's own non-goals.
22	- **CockroachDB and SQLite are exercised in CI only, never deployed live** — only Postgres runs in the actual cluster (LT-52's explicit scope limit). A reader should not expect to find CockroachDB running anywhere.
23	- **No `POST /profiles` write endpoint exists or is planned** — Q2 is search/retrieve by the assignment's own text; a write path was ruled out as scope creep (team-lead + Priya's decision, recorded on LT-39). Review/demo data enters via a version-controlled, idempotent SQL file (`deploy/demo-data/001-review-profiles.sql`) applied as a documented runbook step, not through the API.
24	- **Rate limiting, the touch counter, and the token-issuer's grant limiter are in-process, single-replica-only** — their own code comments state a shared store (Redis) is needed for a genuine multi-instance deployment; this project runs `api-service`/`api-service-issuer` at 1 replica with `Recreate` rollout strategy specifically so this simplification holds correctly, not silently degrading under a rolling update (a real live-tested bug this project found and fixed, not a hypothetical).
25	- **`api-service` calling the connector (LT-33)** is in progress as of this writing — the piece that makes Q2 and Q3 one system, not yet merged.
26	
27	## Acceptance criteria (restated from `backlog.md` S10)
28	
29	- [ ] A cold reader can tell what runs vs. what's a stub without asking — same bar as every hand-off in this project. The "deliberately stubbed" list above is the actual content this criterion requires; the README section should be at least this specific, not a vaguer restatement.
30	- [ ] Test-strategy section states: unit-heavy, integration deliberately stubbed (the assignment doesn't require full end-to-end); the same-PR fake-update rule from `decisions/test-double-strategy.md`, **now also a literal checklist line in `.github/pull_request_template.md`** (LT-42's fix — cite both, since the design doc alone was found insufficient during this project's own review).
31	- [ ] AI tooling note names the actual model/effort tier per story, not just "Claude Code was used": `sonnet, high` for every implementation story in this track's backlog except the connector (`opus, high` — the one seat above sonnet, per `planning-approach.md`'s connector-token-lifecycle exception, because a subtle bug there directly contradicts this project's own threat model). Names the actual orchestration patterns run and what they produced: `decisions/go-layout-debate.md` (package/binary-split decision), `decisions/error-semantics.md` (rotating devil's-advocate, Oren's objections), `decisions/context-propagation.md` (deadline-budget ruling), `decisions/test-double-strategy.md` (hand-written-fakes ruling, Marisol's mitigation). This project is also an org-orchestration exercise across five tracks with hired sub-teams (`PLAN.md`, `CASTING.md`) — worth one sentence acknowledging that's the broader structure this track's own patterns sit inside, without re-explaining the whole org here (that's `../CLAUDE.md`'s job).
32	- [ ] **Added — a real, live-tested finding worth naming, not just the design-time patterns:** this track's own PO review (a Product-track lead running live acceptance checks against the deployed system, not just code review) found and helped fix three real production-shaped bugs during this project — a CI coverage gap that silently skipped two of three backend test suites, a cross-replica rate-limiting bug reproduced by actually crossing the cap live, and a total connector-auth outage from a missing manifest env var. Naming this is itself evidence of the process the AI-workflow note should describe: verification against the live, deployed system, not only against a test suite or a design doc.
33	
34	## Non-goals
35	
36	- No re-explanation of the org-wide orchestration structure (leads, hires, `CASTING.md`) — that's the root `CLAUDE.md`'s and `LOG.md`'s job; this README covers track 03's own AI-workflow story specifically.
37	- No new code, no new tests — this is a documentation story.
38	- No speculative "future work" section beyond what's already named as a stated seam elsewhere (`StopgapAuthorizer`, the vendor stub, Redis for multi-instance) — don't invent a roadmap this project hasn't committed to.
39	
40	## PO review script
41	
42	1. Read the README's "implemented vs. stubbed" section cold, as an evaluator would: can every item in the "deliberately stubbed" list above be found stated plainly, with a reason, not just a bare "TODO"?
43	2. Confirm the test-strategy section cites both `decisions/test-double-strategy.md` and the PR-template checklist line — not just the design doc alone (the exact gap LT-42 found).
44	3. Confirm the AI-workflow note names actual model/effort tiers per story (spot-check against `backlog.md`'s own `Model/effort:` lines) and actual orchestration-pattern outcomes (spot-check against the cited `decisions/*.md` files), not generic claims.
45	4. Confirm the three live-review findings (CI skip, rate-limit/replica bug, connector-auth outage) are named somewhere in the AI-workflow or test-strategy section, not omitted as inconvenient detail — a submission that only shows the clean end-state, with none of the process that found real bugs, undersells the actual work done.
46	
47	## Research team review
48	
49	**Desmond Okafor — claims check:** [pending]
50	
51	**Tobias Lindqvist — objection:** [pending]
52	
53	**Naomi Voss — ruling:** [pending]
54	

{
  "command": "cd /Users/warrenthompson/Source/LoginID && grep -rl \"outage\" --include=\"*.md\" . 2>/dev/null"
}

LOG.md
03-engineering-delivery/decisions/go-layout-debate.md
03-engineering-delivery/refinement/LT-43.md
04-infra-devops/refinement/postgres-in-namespace.md
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && grep -n -i \"outage\" LOG.md 03-engineering-delivery/decisions/go-layout-debate.md 04-infra-devops/refinement/postgres-in-namespace.md"
}

LOG.md:109:**First real token minted at the public URL — and what verifying it found (2026-09-13, 06:30–06:50 PDT).** PR #39 merged after four posts (Priya, Oren, Helena — whose gate was a test for the rehash-persist-failure path — and Nolan); its deploy applied the issuer migration (`successfully migrated database to version: 1`) and `/auth/token` began answering RFC 6749 `invalid_client` 401 to bogus credentials. Theo ran the runbook: four single-scope QA clients (three for `api-service` scopes, one `connector:identity-lookup`), three fictional profiles, Secret `qa-client-credential` with eight keys. **The PM's pre-review mint check found two deploy gaps before the PO touched anything.** First: the search client minted a valid RS256 token (kid, jti, 600 s) and the verifier rejected it — `internal/config` reads `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE` with no defaults and no manifest ever set them, so the token had no `iss` and the verifier compared `aud` against `""`; the QA rows had also been seeded with `aud=api-service` rather than the design literal `loginid-api-service`. Naomi's framing: every refinement doc and unit test had correctly asked "does the code support this variable" and none had asked "does a manifest set it" — the enforcement-site principle in its manifest form. Second, after #41 fixed the env and Theo corrected the seeded audiences live: the token now carried the right `iss`/`aud` and the verifier *still* 401'd — the issuer Service exposes only `443→8080` while `AUTH_JWKS_URL` addresses port 80, so the JWKS fetch was refused and the verifier failed closed **silently** (its log held only the startup line). Fixes in flight: Theo re-ports the Service and audits the others' port mappings against how they are addressed; Renata adds fail-loud startup on unset `AUTH_JWT_*` (PR #42, merged) and a rate-limited log line plus a distinct "verification unavailable" audit event on JWKS fetch failure, so an outage is distinguishable from an attack. LT-41's PR #40 closed Tomasz's per-identity finding and drew a sharper one — the 10k-key cap failed *open* for unseen identities, pre-fillable for ~3 req/s — which Marcus ruled must fail toward stricter: a shared overflow bucket for identities that would need a new slot, existing buckets untouched. The Mac ran out of swap under six lead sessions and two dozen HUD windows; the OS killed the PM's background merge-watchers, so merges moved to heartbeat polling. Naomi's joint review of six stories waits on the port fix.
03-engineering-delivery/decisions/go-layout-debate.md:11:Pattern-matched to a production incident: a shared process/connection pool let a slowly-timing-out downstream partner exhaust the pool and take down an unrelated inbound API — 40 minutes of a partner's problem becoming the platform's outage. Confirmed two binaries closes the *shared-fate* version of that failure (a stalled vendor can't starve `api-service`'s own pool). Flagged what it does **not** close: host/deploy colocation (same node, same FD/CPU budget, same on-call page) is a 04 question, not implied by the binary split; and a self-inflicted retry storm in the connector's token-refresh logic (no backoff) is a failure mode independent of process boundaries entirely. Explicitly not arguing against two binaries — arguing that the boundary alone doesn't buy safety without `context.WithTimeout` on every outbound call and a bounded worker pool.
04-infra-devops/refinement/postgres-in-namespace.md:108:- [x] **Criterion 5 — closed.** PR #33 adds `db: "ok"|"down"` to `/healthz` in verifier-mode `api-service`, via a separate, bounded (1s) `PingContext` check independent of `dao.Repository` (05's contract exposes no `Ping`, correctly avoided amending it for a one-field health signal). Confirmed live at the public URL: `{"status":"ok","service":"api-service","build":"c1fb69d...","db":"ok"}` — only these four fields, no DSN/host/port. Pulled the PR and ran the tests myself rather than trusting the description: `go build`/`go test ./internal/app/...` all pass, including `TestHealthzWithDB_Unreachable_ReportsDownNotError`, which asserts the response body never contains the DSN substring or driver error text when the DB is genuinely unreachable — the one path I can't exercise against the live cluster myself, confirmed by this dedicated test instead. `/healthz` correctly stays 200/`"status":"ok"` even when `db` is `"down"` (a DB outage fails the DB-backed routes, not the process's own liveness probe) — consistent with LT-40's fail-closed design.
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "command": "cd /Users/warrenthompson/Source/LoginID && sed -n '70,95p' 03-engineering-delivery/refinement/LT-41.md 2>/dev/null || grep -n \"AUTH_JWKS_URL\\|JWKS fetch failed\\|unsupported protocol\" 03-engineering-delivery/refinement/LT-41.md"
}

**Tobias Lindqvist — objection:** F3's identical-response-content requirement for `/identity`'s fail-closed error doesn't close a timing side-channel — the three failure branches (no-token, bad-token, vendor-rejected) have inherently different latencies, the last requiring an actual network round-trip to the vendor. Unlike LT-51's dummy-Argon2id case, this can't be cleanly equalized (one branch is a genuinely variable network call). Routed to Marcus for a ruling rather than deciding unilaterally — his own proposed floor is honestly partial, not a full close, which is exactly why this needs a security-owner decision on the trade-off, not a refinement-doc default.

**Naomi Voss — ruling:** All fixes applied, including Marcus's ruling on the timing-oracle question (a ~100ms uniform floor, remainder accepted as a named residual risk in `connector-security.md` §4 — a correctly different resolution from LT-51's fully-closable case, not a half-measure). This refinement is now fully resolved and accepted, ready for Renata.

## Update — write-path gap resolved (team-lead + Priya, on LT-39's record)

**Decision:** no `POST /profiles` story — Q2 is search/retrieve, and a write endpoint would be scope creep beyond the assignment. Review data for the joint LT-34/39/40/51 URL review enters via a version-controlled file, `deploy/demo-data/001-review-profiles.sql` — idempotent, run under the `migrator` role, **never placed under `migrations/`**, obviously fictional values in reserved E.164 ranges, governed by the same discipline as real rows. Applied by Theo as a documented runbook step, after LT-51 lands. See the corrected joint review script in `refinement/LT-51.md` (and `LT-39.md`/`LT-40.md`'s cross-references) — no create step; seed via runbook, then mint → search → read → cap.

## PO in-cluster review — blocking defect found, 2026-09-13 (build `3888b14`)

**Reviewer:** Naomi Voss (PO). `kubectl -n loginid-takehome port-forward svc/idp-connector 8081:443`, confirmed `/healthz` reachable and build-matched, then minted a genuinely valid `connector:identity-lookup`-scoped token (correct `aud: idp-connector-service`, correct scope) via the fourth QA client and presented it to `POST /auth` and `POST /identity`.

**Blocking defect, confirmed from the connector's own logs, not inferred:** every request — the genuinely valid token included, indistinguishable from the no-token and wrong-audience cases — returned 401. Logs: `"JWKS fetch failed (host=, class=network_error): api: fetching JWKS from : Get \"\": unsupported protocol scheme \"\""`. Root cause confirmed in the manifest: `idp-connector`'s `Deployment` in `deploy/manifests.yaml` sets only `HTTP_ADDR` — `AUTH_JWKS_URL` is never set, unlike `api-service.yaml`, which correctly sets it to the issuer's in-cluster JWKS endpoint. The connector's inbound auth is completely non-functional as deployed — not a partial gap, a total one, for every caller. Same class of defect as the earlier `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE` gap (config surface supported by code, never wired into this specific manifest).

**Wider than first reported — team-lead's own check found a second missing variable.** The connector's Deployment sets only `HTTP_ADDR` and `CONNECTOR_JWT_AUDIENCE` — `AUTH_JWT_ISSUER` is missing as well as `AUTH_JWKS_URL`. Also, my own suggested fix value was wrong in one detail: the JWKS URL needs the issuer Service's actual `:443` port explicit (the same lesson from PR #43's earlier fix), not the bare hostname I proposed.

**Durable fix, not just a one-line patch:** Theo adds both missing env vars with the correct port. Renata makes the connector binary refuse to start with either empty (the same fail-loud discipline already added to `api-service` after the earlier issuer/audience gap). Renata also adds a CI test that diffs each Deployment's actual env against what its `APP_MODE`/binary mode requires — a structural check meant to stop this exact class of gap (config supported by code, never wired into one specific manifest) from recurring a fourth time.

**Process note, per team-lead:** this is the third enforcement-site gap of this kind found across the joint review (after `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE` on `api-service`, and the rate-limit/replica gap), and the first one caught by PO review rather than PM pre-review — the process catching it at the layer it's supposed to, not a sign the earlier two passes were careless.

**Verdict: BLOCKED, holding for redeploy.** Cannot meaningfully test audience-rejection, `/identity`'s fail-closed error content, or the timing-floor mitigation when the baseline valid-token case doesn't work at all. LT-41 goes back to In Dev now, returns to In Test when the fix deploys — team-lead will send the build SHA.

## PO in-cluster review — resumed and passed, 2026-09-13 (fix confirmed live)

**Reviewer:** Naomi Voss (PO). **Note on build SHA:** team-lead reported build `f8787fa`; the live pod I actually port-forwarded to reports `ebce65a9e1c8935815e25bad230c59c7c60ca7d0`. Before assuming staleness, I checked the pod's actual live env directly (`kubectl get pod ... -o jsonpath='{.spec.containers[0].env}'`) — both `AUTH_JWKS_URL` (with the correct `:443` port) and `AUTH_JWT_ISSUER` are present and correct on the running pod regardless of which SHA is authoritative. The fix is live; recording the discrepancy honestly rather than either silently correcting it or blocking on it.
Shell cwd was reset to /Users/warrenthompson/Source/LoginID/01-product-industry-research-design

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/refinement/LT-44.md"
}

1	# LT-44 refinement — S11: retention sweep, `DeleteExpired`/`DeleteProfile` wiring
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Renata Cole (03, sweep-invocation code), Theo Bergman (04, `CronJob` manifest + metrics sink); design inputs: Priya Nandakumar (05, retention windows/clocks/classes), Marcus Ilori (02, seat on subject-deletion audit trail if any).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); claims check Desmond Okafor; objection Tobias Lindqvist.
6	
7	## Why this one, now
8	
9	Per team-lead: without this, the README (LT-43, correctly deferred to write last) would have to list PII retention as stubbed — at a company whose own product framing is PII minimization, that's a real, visible gap in the submission, not a cosmetic one. Desmond's LT-43 finding made the case concretely: `DeleteExpired`/`DeleteProfile` exist and are tested on the DAO composite, but nothing schedules or calls either method — a designed-but-not-operational control. This is roughly a half-day story (a `CronJob` calling a `--sweep` mode of the existing `api-service` image, bounded by the already-built `maxRows`, audited) that turns a stub line into a delivered one.
10	
11	## What this story actually is
12	
13	Not new DAO methods — `DeleteExpired`/`DeleteProfile` already exist on the composite (05's `multi-db-strategy.md` §3c) and are already tested (LT-38's conformance suite: `TestConformance_DeleteExpired_*`, `TestConformance_OldestSurvivingAt_*`, `TestConformance_Drained_*`, `TestConformance_DeleteWritesExactlyOneDeletionLogRow`, `TestConformance_DeleteExpired_AlreadyCancelledContextDeletesNothing` — all confirmed present during LT-42's full completeness sweep). This story is the **caller**: a scheduled invocation that loops per `RetentionClass` until drained, plus a subject-deletion request path, plus the health metric that tells 04 whether it's actually running.
14	
15	**Mechanism (team-lead's recommendation, adopted):** a `CronJob` in `04-infra-devops`'s manifests invoking `cmd/api-service`'s existing image in a new `--sweep` mode (or a distinct small entrypoint, `03`'s call) — not a new binary, not a new image build, reusing what's already deployed.
16	
17	## The three retention classes and windows this sweep must implement (from `pii-governance.md`, cited so this story doesn't re-derive them)
18	
19	| `RetentionClass` | Clock | Window | Why this clock specifically |
20	|---|---|---|---|
21	| `direct` | `updated_at` | 24 months | Proposed POC default, engineering basis only — explicitly **not** a legal ruling (`pii-governance.md`'s own "unknown, needs product/legal ruling" status). This story implements the number as configured, doesn't treat it as settled policy. |
22	| `idp_cache` | `updated_at` | 30 days | A cache, not a record — re-hydration costs one `/identity` call, so the window trades staleness against re-fetch cost. |
23	| `idp_cache_orphan` | `created_at`, **deliberately not `updated_at`** | 7 days | Using `updated_at` would let an orphan's own read/re-hydration path reset its expiry indefinitely — the entire reason this class exists as `created_at`-clocked, not a stylistic choice. |
24	
25	**These are stated as "Proposed" in `pii-governance.md`, not "Ruled," except `user_credential`'s no-independent-window rule.** This story implements the configured numbers; it is not this story's job to decide whether 24 months/30 days/7 days are the right numbers — that's Priya's/legal's call, already flagged as open in the source document.
26	
27	## Acceptance criteria (restated from `backlog.md` S11)
28	
29	- [ ] Implements 05's addendum without re-deriving the transaction-boundary or batching reasoning (each `DeleteExpired` call is already one transaction per batch, per the DAO's own implementation).
30	- [ ] Loops `DeleteExpired` per `RetentionClass` until `Drained` is true, one class at a time, never a mixed/shared predicate — enforcement site: the sweep invocation loop's own structure.
31	- [ ] `DeleteExpired` is never called with a request-scoped context — the sweep's own job/scheduler context governs it. Enforcement site: the sweep invocation's context construction (the `CronJob`'s own pod lifecycle, not an inbound HTTP request), plus a test asserting an already-cancelled context returns before deleting anything (the DAO layer already has this test per LT-38; this story's own test confirms the *caller* doesn't accidentally pass a request-scoped one).
32	- [ ] `SweepResult.OldestSurvivingAt` is published to 04's observability **only from a `Drained == true` result** — a non-drained batch reports progress, not health, per `observability.md`'s explicit warning that getting this wrong "means the alert fires on every sweep and gets muted, which is worse than not having it." Enforcement site: the metrics-emission code path, gated on `Drained`.
33	- [ ] Metrics emitted per class per run: `rows_examined`, `rows_deleted`, `oldest_surviving_row_age_seconds{class="direct"|"idp_cache"|"idp_cache_orphan"}` — matching `observability.md`'s exact label values (not the earlier-corrected, invented `vendor_token_cache`/`idp_identity_cache` names that document itself flagged and fixed).
34	- [ ] `DeleteProfile` is the only path used for a subject-deletion request; ordinary application deletes still go through `Profiles().Delete` (no log row) — this distinction is preserved, not collapsed for convenience.
35	- [ ] The `Drained`/`OldestSurvivingAt` coupling gets a one-line doc comment at the field declaration (Oren's note) — already present in the DAO's own code per LT-42's completeness sweep; this story doesn't need to add it again, just not remove or contradict it.
36	- [ ] **The `CronJob` runs against `api-service`'s existing image** (a `--sweep` mode or distinct entrypoint), not a new image build — matching team-lead's stated "half-day story" framing; a new image/Dockerfile would be disproportionate scope for what this needs.
37	- [ ] **Bounded by the existing `maxRows` per call** — the sweep doesn't invent a new batching parameter; it uses the DAO's own already-validated `1..10_000` bound.
38	- [ ] **Audited** — every deletion this sweep performs writes exactly one `deletion_log` row via the DAO's own transaction (already guaranteed by the DAO layer per LT-38's test); this story's job is only to confirm it doesn't bypass that path.
39	
40	## Non-goals
41	
42	- No new DAO methods, no schema changes — `DeleteExpired`/`DeleteProfile` and `deletion_log` already exist and are tested.
43	- No change to the retention windows themselves (24 months/30 days/7 days) — those are Priya's/legal's numbers, implemented as configured, not re-litigated here.
44	- No new container image — reuses `api-service`'s existing image in a new invocation mode.
45	- No subject-deletion-request *API endpoint* — `backlog.md`'s S11 wires the DAO-level `DeleteProfile` path; whether/how an external caller triggers a subject-deletion request (a support-tool button, an API route) is a separate, unscoped question not raised by this story's own criteria.
46	
47	## PO review script
48	
49	1. Confirm the `CronJob` manifest invokes `api-service`'s existing image, not a new one.
50	2. Confirm the sweep loop calls `DeleteExpired` per class until `Drained`, never a mixed predicate — read the invocation code directly.
51	3. Confirm the sweep's context is the job's own, not request-scoped — read the code, confirm the cancelled-context test exists at this layer too (not just the DAO's own, already-covered test).
52	4. Confirm metrics are emitted with the correct label values (`direct`/`idp_cache`/`idp_cache_orphan`), only from `Drained == true` results.
53	5. Confirm the alert rule (`oldest_surviving_row_age_seconds{class="X"} > retention_window + sweep_interval`) is actually configured in 04's monitoring, not just theoretically possible from the emitted metric.
54	6. Once deployed: confirm the `CronJob` actually runs on schedule (check its last-run status via `kubectl get cronjob`/`kubectl get jobs`) and that at least one run reports real `rows_examined`/`rows_deleted` numbers, not zero-across-the-board from day one (which would be consistent with either a genuinely empty table or a broken sweep — the seeded demo profiles, if old enough, are one way to get a non-trivial signal; otherwise this criterion is "ran without erroring," not "deleted something").
55	
56	## Research team review
57	
58	**Desmond Okafor — claims check:** [pending]
59	
60	**Tobias Lindqvist — objection:** [pending]
61	
62	**Naomi Voss — ruling:** [pending]
63	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/04-infra-devops/refinement/LT-46.md"
}

1	# LT-46 refinement — Story 2: secret delivery, re-scoped to Vault
2	
3	**Product Owner:** Naomi Voss (01). **Research team:** Imogen Hale, Desmond Okafor, Tobias Lindqvist. **Engineering:** Theo Bergman (04, manifests); provisioning: Amber (Vault itself); review: Marcus Ilori (02, Vault policies).
4	
5	**Who did the work:** Refined by Naomi Voss (PO); Warren's ruling on the re-scoped criterion.
6	
7	## Why this changed
8	
9	`backlog.md`'s original Story 2 criterion 5 required Kubernetes `Secret` resources encrypted at rest in etcd, enforced via cluster `EncryptionConfiguration` — a control-plane setting on Warren's own shared cluster (confirmed absent when checked directly: no encryption-provider config on the kube-apiserver). Escalated to Warren as accept-residual-or-enable-and-reverify; **his ruling: neither — move application secrets out of Kubernetes `Secret` objects entirely**, into the cluster's existing Vault, delivered via the Vault Agent Injector. This closes the original concern more completely than encrypting `Secret`s at rest would have (a Vault-delivered secret is never written to etcd as a `Secret` object in the first place, not merely encrypted once there) and reuses infrastructure that already exists on this cluster rather than requiring a control-plane change on a shared box outside this project's authority.
10	
11	## Re-scoped criterion (replaces the original etcd-encryption line)
12	
13	Application secret material is not stored in etcd; delivered by Vault Agent with per-`ServiceAccount` Vault roles. Enforcement site: Vault policy per role, plus a namespace check that none of the six application `Secret`s exist.
14	
15	## The six application secrets this criterion covers (enumerated directly from the deployed manifests, not assumed)
16	
17	1. `api-service-jwt-signing-key` — the JWT signing private key, currently mounted only into `api-service-issuer` (LT-32's F13 fix).
18	2. `postgres-superuser` — consumed only by the Postgres `StatefulSet` itself.
19	3. `db-migrator-credential` — the migration-runner credential (DDL rights), consumed by the migration `Job`.
20	4. `db-runtime-credential` — the runtime service credential (DML-only), consumed by `api-service`.
21	5. `issuer-db-migrator-credential` — the issuer's own migration-runner credential (client-store schema).
22	6. `issuer-db-runtime-credential` — the issuer's own runtime credential, consumed by `api-service-issuer`.
23	
24	**Accepted platform exceptions, named explicitly rather than silently grandfathered in as Kubernetes `Secret`s:**
25	- `postgres-server-tls`, `loginid-takehome-tls` — both `cert-manager`-issued TLS certificates. `cert-manager`'s own design outputs a Kubernetes `Secret`; that's the standard integration pattern for this cluster (every other app on it uses the same mechanism per `decisions/deploy-path.md`), not an application secret this project introduced, and not in scope for the Vault migration.
26	- **Open question, flagged rather than assumed either way:** `qa-client-credential` (the review-only QA client credentials from LT-51/LT-41's joint review) — is this an "application secret" that should also move to Vault, or an ops/review-tooling artifact that can reasonably stay a Kubernetes `Secret`? Not decided here; flagging for Theo/Marcus to rule during implementation, named so it isn't silently omitted from either list.
27	
28	## Acceptance criteria for this re-scoped piece
29	
30	- [ ] All six application secrets above are delivered via Vault Agent Injector sidecar/init-container pattern, with a distinct Vault role per consuming `ServiceAccount` — matching the existing per-service RBAC-scoping discipline this project already applies to Kubernetes `Secret`s (never one shared credential across services).
31	- [ ] A namespace check (manual `kubectl get secret -n loginid-takehome` or a CI/audit script) confirms none of the six names above exist as Kubernetes `Secret` objects post-migration.
32	- [ ] Vault policies are scoped per-role to exactly the path(s) that role's service needs — no policy grants broader read access than the specific secret(s) that `ServiceAccount` consumes, mirroring the existing "no ServiceAccount can get/list a Secret it doesn't mount" discipline (`backlog.md`'s own criterion 3, unaffected by this change).
33	- [ ] The migrator/runtime credential separation (criterion 4, unaffected) is preserved under Vault — two distinct Vault paths/roles, not one shared secret with two consumers.
34	- [ ] The `qa-client-credential` disposition (Vault or stays-as-Secret) is explicitly decided and stated, not left ambiguous.
35	- [ ] Marcus (02) reviews the Vault policies before this is called Done — same review discipline already applied to every other security-graded surface in this project.
36	
37	## Non-goals
38	
39	- No change to the TLS-certificate delivery mechanism (`cert-manager` → Kubernetes `Secret` stays as-is) — explicitly out of scope, named as an accepted platform exception above.
40	- No change to the CI runner's own RBAC (still zero grants on `secrets`, already correct and unaffected by where the secrets themselves live).
41	- No re-litigation of which secrets exist or what they're for — this story is a delivery-mechanism change, not a secrets-inventory redesign.
42	
43	## PO review script
44	
45	1. Confirm Vault Agent Injector annotations/sidecars are present on each consuming Deployment/StatefulSet/Job.
46	2. `kubectl get secret -n loginid-takehome` — confirm none of the six named application secrets appear; confirm the two named TLS-certificate exceptions and the `qa-client-credential` disposition are the only ones present (or absent, per whatever was decided).
47	3. Confirm each Vault role's policy is scoped to exactly its consuming service's own secret path(s) — read the policy directly, not inferred from the manifest alone.
48	4. Confirm Marcus's review of the Vault policies happened and is recorded.
49	5. Once deployed: re-review live, per team-lead's own stated plan — confirm the running pods actually receive secret material via Vault Agent (a file mount from the injector sidecar), not a fallback to an old Kubernetes `Secret` left in place by mistake.
50	
51	## Research team review
52	
53	**Desmond Okafor — claims check:** [pending]
54	
55	**Tobias Lindqvist — objection:** [pending]
56	
57	**Naomi Voss — ruling:** [pending]
58