# Project memory

This folder is the long-term memory of the app. It exists so that when we
eventually rebuild from scratch (maybe many times, possibly in a different
language or framework), the rebuild has a complete record of **what the app
does and why**, separate from the code that currently implements it.

## What lives here

```
docs/
  README.md            this file
  features/            one .md per feature area (auth, team, imports, …)
  decisions.md         architecture decisions log (ADR-style)
  tests-catalog.md     stack-agnostic list of behaviors that must hold
```

```
tests/                 vitest tests for pure-logic modules
  clockify.test.ts
  toggl.test.ts
  format.test.ts
  filters.test.ts
```

## The split between docs and tests

- **`docs/features/*.md`** is product memory. It says what each feature does
  in human terms, the original ask, edge cases, who can do what. Code-free.
- **`docs/tests-catalog.md`** is a checklist of testable behaviors. Each
  entry has an ID (`CLK-001`, `TGL-001`, …) and a one-line description.
  Stack-agnostic — when we rebuild, this is the checklist of behaviors the
  new test suite must cover.
- **`tests/*.test.ts`** is the current implementation of those behaviors as
  vitest tests. The test names include the catalog ID. When we change stacks,
  these get rewritten; the catalog stays.
- **`docs/decisions.md`** captures architecture decisions ("why Supabase
  Cloud", "why no auto-mark on transfer", …). Append-only.

## The workflow when adding a new feature

1. **Read the relevant `features/*.md`** first. Is there overlap? Open
   considerations that this feature partially addresses?
2. **Propose the doc update before writing code** — new behaviors, revised
   constraints, new test-catalog entries. Decide together what the change
   actually is.
3. **Implement** — code + vitest tests for any new pure logic.
4. **Update** — finalize the feature doc with what shipped (the Changelog
   section). Add a row to `decisions.md` if a non-obvious choice was made.

## The workflow when fixing a bug

1. Reproduce or describe the bug.
2. If the bug reveals a behavior we hadn't documented, add a new
   tests-catalog entry **before** fixing.
3. Add a failing vitest test (or extend an existing one) for the catalog entry.
4. Fix the code.
5. Update the affected feature doc's Constraints & edge cases section.

## The workflow when removing or replacing a feature

**This folder is forward-looking, not a history museum.** When a feature
goes away — because we replaced it, the underlying need disappeared, or
we changed direction — we **delete** its memory here so a rebuild from
this folder produces only what we currently want.

When a feature is being removed or replaced:

1. **Add a `decisions.md` entry** explaining the swap. This is the only
   place the historical context survives. Reference the doc files
   you're about to delete by name.
2. **Delete the `features/*.md` file.** Don't leave a "deprecated" tombstone
   — `decisions.md` already has the why.
3. **Delete the test files and catalog entries** for behaviors that no
   longer apply. Remove the entries from `tests-catalog.md` and delete
   the `tests/*.test.ts` files (or the relevant tests inside them).
4. **Remove the index row** in `features/INDEX.md`.
5. **Delete the code** — pages, server actions, library functions, DB
   tables, SQL functions, indexes. If a DB table needs to go, ship a
   `drop` migration via `npm run db:push`.
6. **Search for orphan references** — grep the remaining feature docs
   and code for the removed concept; clean up dangling links.

When a feature is being **partially superseded** (one behavior moves to
a different feature, the rest stays):

1. Move the catalog test IDs that apply to the new feature into its
   doc's Tests section.
2. Delete the obsolete catalog entries.
3. Update Constraints sections of any feature doc that referenced the
   removed behavior.
4. Add a `decisions.md` entry for the reshuffling.

**Status field on each feature doc:**

- `planned` — described, not yet implemented
- `in production` — built and currently in use
- `partial` — built but with known incomplete parts (described inline)

`deprecated` is intentionally NOT in this list. If we'd mark it
deprecated, we should just remove it.

## Feature doc template

```markdown
# <feature name>

**Status:** in production | partial | planned
**Lives at:** <route(s)> and <code paths>

## Summary
1–2 sentences. What this feature is, in product terms.

## Why
Dated record of the original ask. Paraphrased from the user's words.

## Behavior
Bullet list of what the feature does. Product terms, not code.

## Constraints & edge cases
Things that can go wrong, things we explicitly handle, things we deferred.

## Permissions
Who can do what. Reference roles (super admin, owner, manager, member).

## Open considerations
Future ideas, known limitations, "we should probably do X eventually".

## Tests
- CLK-001 …
- CLK-002 …
(link to tests-catalog.md)

## Changelog
- YYYY-MM-DD — what changed.
```

## Running the tests

```
npm run test           # one-shot
npm run test:watch     # rerun on save
```