Repository navigation
Testing and delivery
| Area | Checks | Evidence |
|---|---|---|
| Backend quality | Ruff lint/format, scoped service types/rejection proof, export consistency, isolated tests and coverage | Test logs and coverage XML |
| PostgreSQL integration | Full tests against a disposable PostgreSQL database | Database-backed test results |
| Container startup | Image build, migration/startup, HTTP smoke, schema rollback/reapply | Runtime and migration evidence |
| Frontend quality | Prettier, ESLint, TypeScript, OpenAPI drift, Vitest coverage | Type/contract checks and LCOV |
| Frontend browser | Production build, Playwright desktop/mobile, axe accessibility and fault scenarios | Reports, traces, screenshots, standalone build |
| Dependency auditing | Python and npm audits on changes and a schedule | Audit reports |
The verified baseline through PR #23 includes 79 backend tests, four frontend unit tests and six browser tests. Backend coverage has an 85% minimum. Current frontend unit coverage includes libraries and selected components, not the whole UI; browser tests exercise rendering and API integration. Counts alone do not establish production readiness.
PR #284
merged on 4 October after clean final-commit Codex review and passing CI.
make typecheck checks the order/payment services, Stripe adapter and their shared
payment interfaces with pinned strict mypy. make check and backend quality CI
use the same target. Four temporary rejection examples verify wrong order IDs,
invalid terminal states, unchecked nullable checkout URLs and incorrect provider
return assignments. Versioned commands and scope
remain authoritative; other backend files are outside this strict gate.
The separate runtime guards reject a reproduced placement/payment race before creating an unidentified request, and retain reservations when saved requests are missing. All 348 PostgreSQL tests, container/schema smoke checks and browser shards passed. Local coverage was 94.81%; the API contract and runtime dependencies are unchanged. This is scoped verification, not a repository-wide typing claim. VIN-261 holds delivery evidence. The canonical plan and VIN-155 hold current progress.
Frontend quality checks run alongside three browser-test groups on separate runners. Each group builds the same revision and uses its own disposable API/database and fault fixtures. Tests remain single-worker inside each group because those fixtures share mutable state. Every test project, retry and private-data artifact restriction is preserved.
The existing required Frontend · Production build and browser tests check waits for all three groups. Failed, cancelled or unexpectedly skipped groups cannot pass it. Successful groups produce a combined report, and the validated standalone build is published only after all groups pass. Development/production delivery still requires the entire exact-main frontend workflow; a build artifact alone is not release approval. Docs-only PRs retain the existing explicit browser skip.
Each browser group uses the official version/digest-pinned Playwright container with preinstalled Chromium and system dependencies, pinned Node/npm/Python and locked dependencies. Its SDK-version and real browser-launch guard remain enabled.
PR #281 merged this change. Its verified PR run took 4m45s versus 7m56s for the prior main baseline, with the same 141 cases (139 passed, two intentional skips) and 421 unit tests. Aggregate runner duration increased from 548s to 771s: faster feedback trades additional concurrent setup/build work for lower elapsed time. The first merged-main run confirmed 4m44s, again 139 passed with two intentional skips and no retries. These observations are not a guaranteed average or deployment-time claim. The earlier VIN-146 setup/overlap change saved 40 seconds in its comparable main run; it did not speed up browser execution itself.
See the versioned CI guide and VIN-280 evidence and main verification.
VIN-259's bounded journey is verified: catalog, sign-in, cart, checkout, sandbox return and order history have desktop/mobile keyboard and automated checks. PR #273 fixed 320px catalog overflow; PR #282 fixed account-link hydration and a test that scanned the product-loading screen before navigation completed. Three hydration regressions failed before the repair and pass afterward; six complete keyboard journeys passed without retries.
After development delivery
of 5ebde00, twelve read-only guest route/viewport checks at 320×740 and 1280×900
passed with no hydration errors or axe violations. Skip-link focus, visible focus
indicators, mobile-menu keyboard/Escape/focus return and compact action layout
passed. No hosted customer writes were made. This is focused demo evidence, not
full WCAG certification, screen-reader speech verification or Stripe-hosted
conformance. See the versioned evidence guide
and VIN-259 closeout.
The PR coverage comparison workflow tests the exact pull-request head and its Git merge base with each revision's locked dependencies, then compares compatible backend/frontend totals and coverage of changed measured executable lines. Missing or incompatible baselines are reported as unavailable without inferring a pass, and failed head tests fail the job. Comparison summaries and reports are retained for 14 days as supporting evidence alongside existing thresholds. See coverage comparisons.
Regression gates build on the comparison: line and branch coverage may decline by at most 0.5 percentage points against a compatible baseline, and changed measured executable lines require 90% coverage. Ratios use exact arithmetic before display rounding. An unavailable baseline skips only the total comparison; the changed-line gate still applies. See coverage regression policy.
flowchart TD
P[Pull request] --> B[Backend quality, PostgreSQL and container checks]
P --> F[Frontend lint, types, contract and unit tests]
P --> S[Three isolated production-build/browser shards]
S --> E[Require all shards, merge reports and validate build]
P --> A[Dependency audits]
B --> R[Review exact passing commit]
F --> R
E --> R
A --> R
P --> C[Policy-selected external review]
C --> G{Latest commit clean and all threads resolved?}
G -->|No| X[Batch fixes, verify, review changed head]
X --> C
G -->|Yes| R
R --> T[Verify issue acceptance criteria]
T --> M[Squash merge]
VINDOR engineering delivery is linked to the repository. The repository's delivery workflow defines ticket scope, board transitions, PR linkage and completion evidence. The board owns live status; this Wiki explains the system. Scheduled dependency review is not configured.
Issue cards distinguish purple type: epic, blue type: story, red type: bug and grey type: task. Epic titles start [EPIC], so a parent such as VIN-288 remains recognisable even when labels are hidden. Linked children have their own category; one completed child does not complete its parent. Categories are independent of status, priority and workstream. The separate issue forms apply category labels automatically; CLI/API and blank-form issues need explicit classification. See the canonical hierarchy policy for definitions and reclassification. This convention merged in PR #322.
Use the actual GitHub issue number as the project key: VIN-158 means ISSUE #158, not PR #158. Keep PR numbers explicit, for example PR #163 implements VIN-158. Do not invent a separate numbering system.
PR titles use [VIN-N] [type] Description, for example [VIN-158] [fix] Preserve anonymous visitor rate limits. Types: feat, fix, docs, test, ci, chore, refactor, perf. Dependabot retains its upstream-title exception. Open with Issue: linking the issue key and title, followed by Closes #N or Refs #N, then a separate Problem: line. Omit the duplicate Issue section. Then use the canonical template for acceptance, evidence, review and limitations. Keep GitHub's actual Closes #158 or Refs #158 syntax for automation; the VIN alias alone does not close an issue.
New human branch names use type/vin-N-short-description, for example
feat/vin-118-order-drafts or fix/vin-89-cart-recovery. N is the actual issue
number and matches the [VIN-N] PR title. Keep progress on the board, not in
branch names. The owner approved this on 21 September; CI enforcement and all
repository guidance are in PR #179
(merged). It validates naming from trusted main-branch code in a separate workflow,
including docs-only PRs. Workflow execution is not proof that a check is required
by branch protection; verify the live rules before claiming enforcement.
Verified Dependabot branches and documented legacy branches are exempt. The delivery board shows issue cards only,
with PR links inside issues; no separate PR or Dependabot cards. Commit and squash subjects remain Conventional Commits, for example fix(security): isolate customer write limits (VIN-158). Do not copy the VIN-first PR title verbatim as the squash subject. Owner assignment and labels remain in the sidebar. Preserve bot authorship and historical records. The owner approved the bracketed issue/type convention on 21 September; repository instructions and templates were merged in PR #175.
Repository skills document naming, ownership, backend/frontend work and maintenance. Changes are reviewed before merge; an implementation agent's review is explicitly self-review, not independent approval. The review policy selects Codex for non-exempt human PRs and verified Dependabot PRs, and CodeRabbit for qualifying routine documentation. Require the applicable current-head review evidence and resolve findings. The Codex review gate turns bot evidence into an informational status. Missing or stale evidence stays pending; CI and ticket acceptance remain mandatory. Dependabot proposes updates; it does not receive an automatic merge bypass.
The frontend CI produces an artifact after browser tests pass. Vercel hosts development and production, backed by isolated Neon databases. The first production release was deployed from reviewed main through the CLI. GitHub-driven production CD is merged and verified through PRs #49–50, and automatic development delivery from verified main revisions mirrors that gate (#108, hostname fix #113). Reviewed manual PR previews are verified under VIN-45. The first successful automatic release deployed main 88c4ae4. Required-check branch protection is also a separate repository control, not something workflow YAML automatically enforces.
See CI details, contributor guidance, security policy, and live Actions runs.
The informational PR status named Codex review shows a pending indicator and reason while waiting for a review, fixes or clean confirmation. It becomes successful only after its evidence checks pass, but is not sufficient authorization to merge. This is a status indicator, not a percentage estimate. Comment events and a scheduled refresh update it; GitHub may delay scheduled runs. A clean review does not prove a project is production-ready. The shipping agent verifies the task, CI and the reviewed commit before merging without bypassing protection.
Since 8 October 2026 the clean comment's closing is parsed (VIN-325, PR #326). One short phrase can pass, or one :token: such as :+1:. The 80-character limit applies after internal whitespace is collapsed to single spaces. A fixed list of closing words is no longer required. Finding language, a second sentence, and the wrong commit stay pending. Enforced status remains VIN-38.
Review activity resumed on 19 September 2026. Retire the date-bound outage instruction: normal review evidence remains required. The later owner-authorized bounded-review policy is recorded in the repository; the narrow pure-sync carry-forward procedure merged in PR #162 (aceea1d). It is a manual, evidence-backed exception, not automated enforcement: both original reviews, exact-diff/merge-tree proof, interaction assessment and current-head CI remain required. A completed result after merge does not prove pre-merge approval. See the review gate.
On 4 October the owner explicitly moved automatic enforcement outside VIN-155's demo completion requirements. VIN-38 remains open in the post-demo backlog. Current-commit verified external reviews, resolved conversations, applicable CI and protected merges still apply; no branch protection was weakened. Scoped service typing is delivered through PR #284; VIN-262 verifies the final demo package.
The owner merged #37 and authorized completing #35 with remaining enforcement work deferred to #38 in Backlog. A new PR can inherit an old status attached to the same SHA. The status therefore remains informational; safe PR-specific enforcement, protection coverage and recovery verification are not yet delivered. Existing CI and conversation protections remain, with no human approval count. This delivery-specific exception is not a blanket waiver of external review for future PRs.
flowchart LR
M[Merge reviewed PR to main] --> C[All main CI succeeds]
C --> G[Verify exact revision and previous deployment]
G --> D[Forward migrations]
D --> A[Deploy API and check database reads]
A --> F[Deploy storefront]
F --> S[Catalog and session-boundary smoke checks]
S --> P[Successful GitHub production deployment]
Production runs are serialized. Missing, failed, running or stale CI prevents release; already deployed revisions are skipped. Each Vercel invocation explicitly selects its component project and organization. The GitHub production environment and run summary expose the live URL. Failed releases do not automatically downgrade the database. See the environment runbook for secrets, token renewal, rollback and free-tier limitations.
The September 21 policy shipped in PR #173 and was proved by the protected merge of PR #168. That policy allowed eligible patch/minor updates without a per-PR Codex review. The initial queue PRs #165–#171 was completed.
Current policy (PR #308, merged 5 October 2026): verified Dependabot PRs use Codex reviews covered by the existing subscription allowance. CodeRabbit's bot seat was unavailable on the Free plan. This replaces the CodeRabbit-only routing from PR #217 and its provider-specific retries in PR #218.
The continuation introduced by PR #214 retains offline Python export repair and serial protected merges. It requires verified clean Codex evidence for the current PR revision, resolved findings and all applicable CI before an Actions approval and SHA-bound protected merge. A shared commit status alone cannot authorize delivery. Human-authored PRs retain their existing policy, including the narrow routine-documentation exception.
Requests are deduplicated per head. Only a trusted, unedited, recognized Codex quota response permits a retry: at most two retries, after 24 hours and then seven days following the respective quota response. Later review activity supersedes a quota notice. Missing/unknown evidence, exhausted quota and genuine failures keep delivery pending; there is no paid API or credit-purchase fallback.
The repository credential expires 28 October 2026 and needs renewal before expiry. No scheduled chat wakeup or paid API is configured.
VIN-172 is reopened for live verification. Live proof of the replacement workflow is still pending; local tests and the earlier PR #168 do not prove it. Keep bot PRs out of the board. The versioned policy is authoritative. Workflow-file merge permission remains a tracked configuration check on VIN-172; no extra token permission has been granted.
All repository issues carry a priority label and a milestone and belong to the delivery project. High means core demo or active delivery work; medium means supporting delivery efficiency/evidence; low means post-demo follow-ups. Dependencies and blocked status still determine which item can start. Priority is separate from workflow status, and a milestone is a target outcome, not an invented delivery date.
The canonical portfolio plan owns sequencing. VIN-147 follows portfolio delivery unless a concrete blocker requires a bounded repair. Existing Customer accounts milestones are preserved; priorities added to closed tickets are retrospective classification. Cancelled VIN-42 remains closed as not planned and archived in the project, not marked delivered.
The checkpoint guidance, delivered in PR #201 (VIN-200), defines verification before implementation and stopping at the authorized finish line. Its handoff checker validates evidence fields only; it does not establish review approval, verify external results or install scheduled work.
The monitoring runbook preserves dated VIN-223/VIN-230/VIN-232 hosted trace evidence, safe labels, release/HTTP metadata and sampling limitations. Historical filtered traces are unchanged; one connected sample is not a p95/p99 baseline. Portfolio progress belongs to the canonical plan.
VIN-158’s verification mechanism in PR #244 has completed hosted acceptance and diagnostic cleanup. Its same-instance runbook uses bounded real workstation/runner ingress, an opaque witness from the actual limiter, atomic server ordering and the actual budget to exclude cross-window false positives. Diagnostics are default-off and development-only. Closeout verified both flags disabled, Ready redeploys and absent diagnostic headers on both direct API and storefront failed-login responses. Keep the reusable hook/tests disabled for future regressions; retain the issue as the evidence/handoff source.
PR acceptance checklists list only outcomes actually verified in that PR. Pending CI/review is disclosed separately, and genuine post-merge verification stays open on the source issue until proven. Never tick unverified work, keep checked placeholders, or hide unfinished scope to imply completion. The versioned creation/ownership skills, PR template and delivery guidance are aligned in PR #233; installed local guidance is also updated.
Keep future trace naming work small and separate from VIN-232 and the remaining portfolio delivery priorities. Consider clearer directional labels, less redundant table columns and explicit code-owned mappings for useful framework operations after inspecting actual SDK envelopes. Generic fallback labels are deliberate privacy protection. Do not expose arbitrary operation strings merely because they match a regex; do not drop all sub-millisecond spans without evidence that their loss is acceptable. The monitoring runbook already explains bounded labels. No naming implementation or sampling change is authorized by recording this feedback.
The feedback was reviewed against current code without treating the third-party recommendations as implementation instructions. VIN-158 is complete; follow the canonical portfolio plan for the next priority.
| Feedback | Disposition |
|---|---|
| Process-memory limiter | Real per-instance limitation; “does not work” overstates it. VIN-158 hosted identity/configuration proof and diagnostic cleanup are complete. Its same-instance proof does not establish distributed protection. Shared counters require a separate demonstrated requirement; no automatic Redis/Postgres replacement. |
| Reservation recovery | No periodic sweep exists, but expiry webhooks and customer reconciliation already do. Candidate for a small future ticket: provider-authoritative automated recovery with escalation. It must not release uncertain stock solely because a deadline elapsed. |
| JWT revocation and register enumeration | Real documented/observable tradeoffs. Candidate for scoped security decisions; token versioning needs migration and session semantics, not just a column. |
| Password recovery and refunds | Reuse VIN-127 and VIN-128; do not duplicate or bundle unrelated account deletion/email verification. |
| Placeholder/CORS/health cleanup | Deferred maintenance. Confirm consumers and measured noise before changing behavior; localhost CORS is not wildcard-origin credential exposure. |
| CI/process overhead | Reuse VIN-147 and VIN-84; measure duplication and duration without weakening gates. |
| Missing cancellation, search, images and PostgreSQL concurrency coverage | Overstated: managed unpaid cancellation, storefront search/filter/sort, licensed images and PostgreSQL concurrency CI already exist. No duplicate ticket. |
| Fulfilment, categories, variants and admin product UI | Product expansion outside the current demo finish line. |
This register stores the feedback and its disposition. Candidate items are not active work, completed acceptance, or newly created issues. Refine only the selected next item into an independently testable ticket before implementation.
PR #254 deployed the report-only stage as ec29964 through gated development/production delivery. Both hosted API documentation UIs passed nonce equality, Swagger health execution and ReDoc worker search with zero observed DOM policy reports. Hosted development storefront HTML omitted framework-script nonces despite its fresh policy nonce and private/no-store caching; this is a failed acceptance check, not a completed CSP outcome. At this staging checkpoint, enforcement remained off pending corrected hosted behavior.
VIN-126 retains the exact revision, failed evidence and corrective PR. A disposable local fixture reproduces the missing nonce by stripping standard CSP request headers during internal forwarding. The guarded compatibility patch and later promotion belong to that same ticket; no additional portfolio credit is granted by partial merges. Follow the canonical plan and policy runbook.
The later nonce correction in PR #255 deployed as b7f1f66 through successful gated development and production delivery. Public checks in both environments passed fresh repeated-page/script nonce equality, private/no-store HTML, baseline headers, caller-policy rejection, immutable caching, product navigation and documentation execution/search without observed unexpected policy reports. Existing development Sentry delivery returned HTTP 200; production monitoring stays off. PR #256 completed the focused enforcement promotion as cc115e093ad355882e7ce983bf35703f718a9609, after passing current-head CI and a trusted clean Codex review. The owner merged it; that closing phrase was not recognized at the time and was recorded under VIN-38, without another model request. VIN-325 later parsed short signoffs. VIN-38 still tracks enforced status. Actual gated development and production deployment jobs succeeded. Both isolated public hosted checks passed enforced-policy nonce equality/freshness, headers, caching, navigation and API documentation, with zero unexpected policy violations. An untrusted inline script was blocked under the actual hosted policy in a controlled browser response. Development Sentry transport returned HTTP 200; production monitoring remains inactive. Full disposable desktop Chrome/Pixel 7 fixtures passed 137 browser cases with two existing skips; public hosted checks do not claim private checkout writes or Safari coverage. This completes VIN-126’s one existing outcome; PR #257 records the canonical plan closeout. Staging and corrective PRs add no separate progress credit.
VIN-155’s current priority handoff links the bounded remaining demo stories and wider backlog dispositions. Source issues own scope, dependencies, proving vehicles and unresolved decisions; the canonical plan is the sole checklist. At that 2 October checkpoint, VIN-45 was verified and VIN-258 restore was next; subsequent restore, accessibility, typing and final-package closeouts supersede that historical priority. These bounded demo checks are separate from broader enterprise guarantees.
PRs #264, #265 and #266 delivered guarded manual frontend previews, exact-origin sessions and operator guidance. One completing protected preview from reviewed 6d46eff passed the full fictional login/cart/account/host-isolation journey, exact source identity, enforced HTTPS/security headers and all five application-origin cases. VIN-45's complete evidence records results and limits. Test carts were emptied and both sessions signed out. The owner separately approved replacing the existing unidentified Hobby share link; the dashboard test link had no automatic expiry and was revoked immediately after the probe. Private local file/clipboard were cleared and the receiver stopped. No persistent project-wide bypass was created.
Retirement run 37073917725 removed the exact completing preview with provider/public 404; both test previews are retired and stable development/production aliases remain available. PR #267 merged final versioned reconciliation as 160ab3e after passing applicable CI and clean current-head Codex review. VIN-45 is complete. Earlier uninstrumented quantity drift remains a VIN-260 observation, not a claimed fixed defect. No automatic preview platform, preview Sentry activation, paid upgrade, production activation or schedule was added.
VIN-258 is verified after PR #268 merged. A clean merged-revision rehearsal of 0f547cb on 3 October verified separate local PostgreSQL source/target, schema/data/sequences, catalog/login/cart/order ownership, corrupted-archive rejection and cleanup. The runbook distinguishes the measured 0.083-second restore of tiny fictional data from hosted recovery guarantees. No cloud database was accessed. The source issue contains the complete sanitized evidence and exact review scope. The canonical plan remains the progress source; the versioned restore closeout is merged. VIN-269 remains open for upstream remediation under the approved temporary exception below.
The owner's security/logging feedback was independently checked against clean main. Nonce equality/freshness, deny behavior, spoofed forwarding and documentation-browser CSP checks already exist. The security runbook separates trusted application schemes from Vercel edge HSTS. Optional policies require compatibility decisions, particularly Swagger OAuth. The unused core/logging.py is initial scaffolding; active logging is in main.py and core/observability.py, not CloudWatch. Removing that misleading placeholder is a future cleanup candidate, not a demonstrated monitoring defect or active implementation. Tests were inspected for this feedback, not rerun by the investigator. No separate duplicate ticket was created.
The complete audit still reports the existing development-tool braces advisory.
The owner-approved exception was extended once on 8 October and now expires
17 October 2026 at 23:59 UTC; it is accepted risk, not a security fix. Exact
dependency-file hashes and advisory paths restrict its scope. Other findings,
runtime exposure, changed dependencies, invalid audit evidence and expiry fail;
runtime auditing remains mandatory and clean. Full raw reports and the explicit
accepted-risk job summary remain visible. No protected check is disabled. The
versioned policy
owns the command, scope and removal rules; do not extend or repin it silently.
PR #286 reconciles the existing guides with a clean isolated bootstrap and fresh hosted sandbox purchase. The versioned rehearsal identifies the tested revisions, stopped local resources, retained fictional paid record and timing limits. The shopping segment took 4m01s; setup and narration were not timed. Monitoring, restore and accessibility proof retain their original dates and bounded scope.
Use the canonical plan and VIN-155 for completion, rather than another Wiki checklist. Deferred automatic review enforcement, expiring dependency risk, process-local rate limits, copied JWTs and late-write ordering remain explicit. Customer features follow the scoped demo.
Engineering handbook · Repository · Versioned documentation