full repo review

gistfile1.txt

# Repo Audit — Planned Scope + Readiness

Use this when there is a credible plan: PRD, spec, beads, contracts, backlog, design docs, or another trustworthy artifact that defines intended scope.

## Objective

Perform a ground-truth audit that answers **two separate questions**:

1. **What functionality exists and is proven end to end?**
2. **Compared with the explicit plan, what is missing, partial, conflicted, dead, or risky?**

Do not collapse those into one unsupported number.

- **Readiness** is about what is actually implemented and verified.
- **Completeness** is about what exists relative to explicit planned scope.

## Preconditions

Start by declaring the audit mode:

- **PLAN-BACKED** — one or more credible plan artifacts exist and are materially usable
- **CONFLICTED-PLAN** — multiple plan artifacts exist but materially disagree

If no credible plan artifact can be found, stop treating this as a plan-backed audit and say:

> No trusted plan found. Use the “Repo Audit — Capability Readiness (No Trusted Plan)” prompt instead.

If plan artifacts conflict, do **not** merge them into a single denominator. Keep source-specific comparisons visible.

## Non-negotiable rules

1. Do not tell me what *should* exist. Tell me what **does** and **does not**, with evidence.
2. Run the code when possible. Do not trust docs.
3. Docs/specs/beads/tickets define the plan; they never prove the implementation.
4. If two plan sources conflict, report both and keep the conflict visible.
5. Dead code, unregistered routes, one-way data flows, and uncalled workers are findings.
6. Do not stop at the first failure. Continue the audit and mark blocked areas explicitly.
7. Do not output a single completeness percentage unless the denominator is explicit and evidence-backed.
8. Stale docs that could cause a false ship decision are findings. Severity depends on shipping risk.

## Evidence hierarchy

Use this evidence ladder and label findings accordingly:

1. **Runtime proof** — command output, rendered UI, HTTP response, DB mutation, emitted event, worker execution, job run, side effect
2. **Executed test proof** — unit/integration/e2e/bdd output that actually exercises the path
3. **Static reachability proof** — registered route, linked page, nav item, handler registration, scheduled job registration, resolver wiring, dependency injection wiring
4. **Static code-only proof** — code exists but reachability is not proven
5. **Plan-only proof** — docs/specs/tickets/contracts that define intention only

Rules:

- Do **not** mark a capability **✅ Proven end to end** without runtime proof or executed-test proof.
- If code appears wired but proof is blocked by env, secrets, external dependencies, or broken setup, mark it **⚪ Blocked / unverified**.
- Docs can define the plan. Docs can never prove the implementation.

## Source of truth hierarchy for the plan

When determining planned scope, use these sources in order:

1. Machine-readable contracts (OpenAPI, GraphQL schema, JSON schema, typed interfaces)
2. PRD / specs / beads / design docs in repo
3. Issue tracker / backlog / tickets
4. Figma / UX docs
5. README / HANDOFF / session notes

If sources conflict, report the conflict as a finding.

## Define “capability” before auditing

A **capability** is a user goal or system responsibility with:

- a trigger or entry point
- an executable path through shipped code
- an observable outcome or side effect
- at least one failure mode

A capability is **not** just:

- a component
- a helper
- a schema or DTO
- a table with no consumer
- an unregistered route
- dead code

Examples of valid capability units:

- Sign in
- Create project
- Invite teammate
- Upload file
- Submit checkout
- Generate report
- Process webhook
- Send notification
- Retry failed job

## Severity rubric

- **P0** — blocks shipping, breaks a primary ship unit, critical security gap, or makes verification impossible for a core journey
- **P1** — blocks planned completeness or leaves a core capability partial/unreliable
- **P2** — quality, resilience, observability, or maintainability issue that does not block ship alone
- **P3** — low-risk cleanup, polish, or documentation issue

Verification failures on a **primary ship unit** are **P0 unless clearly isolated and justified**.

## Required workflow

### Phase 0 — Discover ship units, commands, and environment

Identify:

- repo structure, frameworks, package managers, monorepo layout
- deployable units: web app(s), API(s), worker(s), cron/scheduler(s), admin app(s), CLI(s)
- command sources: package.json scripts, Makefile/justfile, turbo/nx config, CI workflows, Docker/compose, test configs
- env setup sources: `.env.example`, compose files, seed scripts, mock servers, testcontainers
- git state: current branch, `git status`, obvious local changes that may affect audit trust

Output:

- **ship units**
- **verification command matrix**
- **required env/dependency blockers**

### Phase 1 — Build the canonical capability inventory

Build a capability inventory from the actual codebase and runtime surface before comparing to the plan.

Use:

- registered frontend routes/pages
- navigation/menu items
- forms/actions/mutations
- registered API routes/procedures/resolvers
- workers, queues, cron jobs, schedulers
- inbound/outbound webhooks
- CLI/admin entry points
- DB tables with actual consumers
- feature flags that gate reachable flows

Group low-level artifacts into capabilities by **user goal** or **system responsibility**.

For each capability, record:

- capability name
- actor (guest, user, admin, system)
- domain
- entry point(s)
- UI route(s), if any
- API/procedure(s), if any
- worker/webhook/job(s), if any
- DB/storage touched
- external integrations
- auth boundary
- feature flags, if any
- plan tag: **Planned / Unplanned / Unknown-plan**

### Phase 2 — Baseline: can it run?

For each primary ship unit:

- confirm boot path
- run all relevant verification commands discovered in Phase 0, including where applicable:
  - lint
  - typecheck
  - unit
  - integration
  - e2e
  - bdd
  - build
  - smoke / health checks
- record pass/fail for every command
- identify missing env vars, secrets placeholders, broken dependencies, failing migrations, missing services

Output:

- **state of the build**
- **every red command**
- **runtime blockers**

Do not stop at the first failure. Continue and mark blocked areas explicitly.

### Phase 3 — Capability-level end-to-end verification

For each core capability, verify the full chain:

**entry point → auth/authz → validation → business logic → DB/storage/side effect → response/UI state → error handling → observability → tests**

Check:

- Is the entry point reachable in shipped code?
- Is auth/authz actually enforced?
- Is validation present and active?
- Is the business logic real, or stubbed / mocked / TODO?
- Does data persist where expected?
- Are async jobs/webhooks actually triggered and consumed?
- Are loading / empty / error states implemented?
- Are failures handled, surfaced, retried, or compensated?
- Is there runtime or executed-test proof?
- Is telemetry or error tracking actually emitted?

For every non-✅ capability, identify the **exact broken link**.

### Phase 4 — Supporting audits by layer

#### API & business logic

- Inventory registered routes/endpoints/procedures from code, not docs
- Compare against planned interfaces where they exist
- Check auth, validation, side effects, transactions, error handling
- Flag TODOs, mocks, dead code, feature flags, stubs
- Verify ORM usage, constraints, schema alignment

#### Frontend flows & integration

- Inventory pages/routes/components and the journeys they enable
- Compare against planned screens/flows where they exist
- Verify UI → API → loading/empty/error states → validation
- Flag placeholder UI, hardcoded data, dead-end pages, broken nav
- Check whether a new user could understand the product from the UI alone

#### Data layer & integrity

- Inventory tables/entities by domain
- Verify migrations versus actual usage
- Check constraints, indexes, RLS, foreign keys, orphan risk
- Flag unused tables, data silos, consumers with no backing data

#### Async jobs & external integrations

- Inventory queues, workers, cron, webhooks, email/SMS, storage, payments, AI calls, third-party APIs
- Verify trigger → processing → persistence → retry/failure path
- Check idempotency and dead-letter handling where relevant

#### Tests & confidence

- Run all test suites
- Map tests to critical capabilities
- Flag `.skip`, `.only`, flaky tests, stale assertions, untested error paths
- Compare bdd/e2e claims against what actually executes

#### Security surface

- Verify auth/authz, middleware, RBAC, tenant boundaries
- Check validation and sanitization at server and client boundaries
- Flag sensitive data leakage, secrets in code, unsafe logs, insecure storage
- Verify test/dev flags cannot leak into production paths

#### Observability & feedback loops

- Inventory analytics, error tracking, tracing, LLM observability
- Check whether events are emitted or merely defined
- Verify whether closed loops exist where product behavior claims they should
- Flag dead observability code and one-way telemetry

#### Deployability

- Inspect CI/CD gates and whether they match the current code
- Check Docker/infra/config drift
- Verify health checks, readiness probes, startup/shutdown behavior
- Answer per ship unit: **can this ship?**

### Phase 5 — Planned scope comparison

Compare the capability inventory against explicit plan artifacts.

For each planned capability, classify it as:

- **✅ Proven end to end**
- **🟡 Happy-path only**
- **🟠 Partial chain**
- **🔴 Not implemented**
- **⚪ Blocked / unverified**
- **⚫ Dead / orphaned**

Rules:

- A planned capability with code but no reachable entry point is **not implemented** or **dead/orphaned**, not “done”.
- A planned capability with UI only or API only is **partial**, not implemented.
- A claimed feature that fails runtime verification is **not complete**, even if most of the code exists.
- If plan sources disagree about whether a feature is in scope, report the conflict instead of picking a favorite.

### Phase 6 — Tracer bullets (vertical slices)

Identify the top **5–10 core user journeys** from the product.

Selection priority:

1. planned core journeys from the most authoritative plan source
2. high-prominence journeys from current navigation and auth/onboarding
3. creation/edit/mutation flows
4. payment/report/export/automation flows
5. critical system jobs and integrations

For each tracer bullet, verify the full slice:

**UI → API → DB/storage → async work (if any) → response → error states → telemetry → tests**

For anything not ✅, specify the **exact broken link** with evidence.

## Capability status rubric

Use these statuses for every capability:

- **✅ Proven end to end** — runtime or executed-test proof; happy path works; error handling exists; auth/validation present; side effects verified
- **🟡 Happy-path only** — main path works, but error handling, edge cases, observability, or tests are incomplete
- **🟠 Partial chain** — one or more required links are missing, stubbed, mocked, broken, or unverified
- **🔴 Not implemented** — planned, but no reachable implementation exists
- **⚪ Blocked / unverified** — code appears wired, but proof could not be obtained because of a blocker
- **⚫ Dead / orphaned** — code exists but is not reachable from any shipped entry point

## Required deliverable format

### AUDIT MODE

- PLAN-BACKED or CONFLICTED-PLAN
- Plan artifacts found
- Most authoritative source(s)
- Plan conflicts

### EXEC SUMMARY

- Ship units audited
- Build health: pass/fail per verification command
- **Discovered functionality readiness:** X/Y capabilities are ✅
- **Critical journey readiness:** X/Y tracer bullets are ✅
- **Planned completeness:** X/Y planned capabilities exist and X/Y are ✅
- Biggest risks to shipping: top 3

### PLAN ARTIFACTS & CONFLICTS

- [Source] — [Why it is authoritative or stale]
- [Conflict] — [Sources involved] — [Impact on denominator]

### VERIFICATION FAILURES (P0 unless justified otherwise)

- [Command] — [Ship unit] — [Error] — [Root cause] — [Fix]

### CAPABILITY INVENTORY

For every capability include:

- Capability
- Actor / domain
- Planned? (yes / no / unknown)
- Entry point(s)
- UI / API / worker / DB / integration touchpoints
- Auth boundary
- Tests
- Observability
- Status
- Exact weak link
- Evidence
- Suggested fix

A tabular summary is preferred with these columns:

| Capability | Planned? | Entry point | UI | API | Worker | DB | Auth | Error states | Tests | Observability | Status | Weak link |
|---|---|---|---|---|---|---|---|---|---|---|---|---|

### GAPS: PLANNED VS IMPLEMENTED

- [Capability] — [missing / partial / stubbed / conflicted] (Severity)
  - Evidence: [file path + symbol + line]
  - Plan ref: [doc / ticket / contract / section]
  - Fix: [1–3 concrete actions]

### UNPLANNED LIVE FUNCTIONALITY

- [Capability] — [status]
  - Evidence: [entry point + file path]
  - Risk: [low / medium / high]

### DEAD / ORPHANED CODE

- [Artifact] — [why it is unreachable]
  - Evidence: [file path + registration absence / call-site absence]

### DATA FLOW ISSUES

- [Source → expected destination] — [what is broken / missing]

### OBSERVABILITY GAPS

- [What should be tracked] — [is it emitted?] — [evidence]

### BUGS (Reproducible)

- [Bug] (Severity)
  - Repro: [steps or command]
  - Expected: [X]
  - Actual: [Y]
  - Evidence: [file path + line or runtime output]

### SHIP DECISION

Per ship unit:

- **GO**
- **GO WITH EXPLICIT RISKS**
- **NO-GO**

### PRIORITIES (Ranked)

- **P0:** must fix before shipping / verification blocked / critical security or runtime failure
- **P1:** blocks planned completeness or core journey readiness
- **P2:** quality / hardening
- **P3:** cleanup / polish / low-risk docs

## Finding format requirements

Every finding must include:

- **Severity**
- **Evidence** — file path + symbol + line when useful
- **Plan reference** — contract / PRD / bead / ticket / design section when applicable
- **Suggested fix** — 1–3 concrete actions

## Final instruction

Do not write a narrative that hides the truth. Produce an auditable report that makes it impossible to confuse:

- what is planned
- what is implemented
- what is reachable
- what is proven
- what is blocked
- what is dead