# Crystal — the growth of a project as a shape (spike)

Status: a working spike, not a product. It replays this repository's own git history as the Facet "Shape Progress" picture. Reachable at `/crystal` (it lives in `tools/private/`, so it is not on the home grid). Nothing here changes Facet.

Name: Crystal, because a crystal grows by adding facets and Facet is the sibling it comes from. Working name only.

Read this file first, then `FACET-CONTEXT.md` (where to look in Facet, what is forked and what Facet already learned the hard way), then `SPIKE-LOG.md` (what the spike showed) and `data/README.md` (the data format).

## The idea in one paragraph

Facet draws a task list as a shape: every category is a corner, the outline is how many tasks it has, the bright inner shape is how many are done, and played back over time the shape grows, buds a new corner when a category is added, folds one when it is removed, and leaves faint rings of where it has been. A vibe-coded project is often the opposite of a task list: nobody wrote the tasks down first, the plan changes every session, and what you want to see is the idea growing from a first sketch to something finished. Crystal keeps the picture and changes what feeds it. The corners are the areas of the project (concept, UI, core logic, data, integrations, tests, docs, deploy, or whatever the project turns out to have), the outline is how much exists in each, and the inner shape is how finished each one is, worked out from signals that can be read automatically (git history first) instead of a checklist someone maintains.

## What the picture means in Crystal

- **A corner** is an area of the project. It buds out of the shape the first time something exists in it and folds back in if everything in it is deleted.
- **The outline** is the size of the area: how much has been built there. In the spike it is the number of files that exist in the area. It grows as the idea expands.
- **The bright inner shape** is how finished each area is. In the spike it is the share of the area's files that have not been touched for three days, the idea being that an area that has stopped churning has settled. This is the weakest part of the spike and the thing most worth improving (see "Defining done").
- **The big faint number in the middle** is the overall share (settled, in the spike).
- **The trail** is faint outlines of earlier moments: the growth rings of the project.
- **Time** is real time, from the first commit to now, so a quiet month is a long calm stretch and a burst is a fast one. Playback length is a setting (30 seconds to 3 minutes).
- **Square-root radius**: Facet scales radius linearly with the biggest category ever; Crystal uses a square-root scale so one huge area (the tools folder, in this repo) does not shrink everything else to a dot.

## Why git first

A repository's history already contains a time-lapse. `git log --name-status` gives, for every commit, which files were added, changed or deleted and when, with no setup and no manual entry, so any existing project can be replayed the first time you point the tool at it. It also fits how vibe coding works: the work happens in commits and sessions, not in a planning document. Everything else in this file (session transcripts, test results, checklists, manual sliders) is an extra signal layered on the same model.

## The data model

One file per project, `crystal-progress/0` (full spec and an example in `data/README.md`):

- `categories`: the areas, each with a name, a colour and the rule that put files in it.
- `snapshots`: a list of moments. Each has `at` (milliseconds), optionally the `commit` and its subject, and for every category `{ total, sum, commits }`.
- `total` is the outline, `sum` is the inner shape (so `sum <= total`), `commits` is the number of commits that have touched the area so far (not drawn yet; kept for glow and tooltips).

This is deliberately the same shape of data Facet's Shape Progress already consumes, `{ names, colors, pts: [{ at, cats: [{ has, total, sum }] }] }`, so the renderer is reused as it is. A new source of data means a new importer that writes this file, nothing more.

## Signals and metrics (what can feed the shape)

Built in the spike:

- **Git history** (`ingest/git-to-crystal.mjs`): files that exist per area (outline) and files untouched for N days (inner). Needs only the repository.

Next, in rough order of value for effort:

- **AI session records.** A Claude Code Stop hook (see the `session-start-hook` skill for how hooks are set up in cloud sessions) could append one snapshot at the end of every session to a file in the repo, so each session is a frame even when it made no commit. The session transcript (`.jsonl` under the user's Claude projects folder) lists every Edit and Write with its path and every command run, which gives per-area activity, test runs and failures. This is also the natural place to record which commits were AI-authored (the `Co-Authored-By` trailer is already there).
- **Test results per folder.** The share of tests passing per area (or per test file mapped to an area) is a real "is it done" signal for the areas that have tests.
- **Checklists in plan files and issues.** `PLAN.md` style lists, `- [ ]` lines, GitHub issues and PRs with labels. For an area that has them, this is exactly Facet's own measure (tasks and done), so a hybrid is possible: use the checklist where one exists and the file signals where it does not.
- **Manual sliders.** A 0 to 100 "how finished does this feel" per area, set in a quick check-in. Cheap, honest about being a feeling, and good for the areas no signal reaches (design, copy, "is this actually fun").
- **Deploy and runtime signals.** Whether the area is deployed, whether it has been opened recently, Lighthouse or error counts. Later.
- **Code-quality signals.** Churn (the same files edited again and again), fix-commit share (commit subjects starting `fix`), file size growth, TODO and FIXME counts. Good for texture (a wobble, particles) rather than for the main shape.

## Defining "done" (the open design problem)

A task list has an obvious done. A project area does not. Options, from simplest to richest:

1. **Settled (built).** Done = not touched for N days. Free and automatic. Weakness: an area abandoned half-built looks done, and an area being actively polished looks unfinished.
2. **A maturity ladder per area.** idea (0.1), sketch (0.3), working (0.6), tested (0.8), documented (0.9), shipped (1.0), each rung read from signals: any code present, any test touching it that passes, a README or notes mentioning it, deployed. The inner shape is the rung, not a count of files. This is the recommended next step because it expresses "growing from concept to complete" directly and does not depend on anyone writing tasks.
3. **Checklist ratio.** Facet's own measure where a list exists.
4. **Test pass share.** For areas with tests.
5. **A blend** with the method shown in a tooltip, so the picture is honest about what it is built from.

The spike uses option 1. The roadmap below moves to option 2 with option 1 kept as one of its inputs.

## Defining the areas (taxonomy)

- **Path rules (built).** First match wins, in order: assets and media, docs and notes, build and scripts, site shell, API, config, tools, other. They are hard-coded in the importer for this repo and meant to move to a per-project config file such as `.crystal/areas.json` (`{ "areas": [{ "name": "UI", "globs": ["src/ui/**", "**/*.css"] }, ...] }`).
- **By tool (built).** For a repo that holds many apps, the corners are the most-touched app folders plus "Other tools" and "Platform". A renamed folder keeps one corner through an alias (`--alias old=new`; this repo's `task-list` to `facet` rename is built in).
- **Semantic areas (not built).** For a project whose areas are features rather than folders (auth, onboarding, billing), a cheap model pass over commit subjects and file names could propose the areas, which a person then merges and renames. The result should be written back to the config so the picture is stable between runs.
- **Limits.** The renderer handles up to 16 corners but reads well with 5 to 9. More than that: merge the small ones into "Other", or switch to the tool grouping.

## Visual encodings (what each channel could mean)

| Channel | Spike | Possible later |
|---|---|---|
| Corner | an area | the same |
| Outline radius | files that exist (square-root scale) | planned plus existing (issues, TODOs) |
| Inner shape radius | share settled | maturity rung |
| Corner ring | share settled | rung, with a closed ring and a tick when shipped |
| Edge glow / burst | whole-file settling waves | commits landing, fix commits as red particles |
| Wobble | none | churn: the same files edited again and again |
| Trail | outlines of earlier moments | the same |
| Colour | fixed per area | per area, kept stable across runs |
| Finished project | none | when every area is shipped the shape locks in as a crystal (a still, with a final glow) |

## Architecture options

1. **Fork (what the spike does).** `lib/shape-fork.js` is the renderer copied out of Facet with three deliberate changes. Cheap, no risk to Facet, and the right choice while the data and the meaning are still being found.
2. **Shared module.** Later, move the renderer (`rpDraw` and its layout and presence code) into a small shared file that both Facet and Crystal load. Facet's own code already separates it from the live view (`rpDraw(V, ...)` takes a view state object), which was done for the video export, so this is a small refactor when the time comes. Facet's video export (`rpExportVideo`, `MUX`) would then work for Crystal too.
3. **Ingestion runner.** Options: run `ingest/git-to-crystal.mjs` by hand (the spike), run it on every push in a GitHub Action and commit the file, or run it from a Claude Stop hook at the end of each session. The hook is the best fit for "snapshots per vibe-coding session".
4. **Where the data lives.** A committed `.crystal/progress.json` in each project's repo (diffable, no server, travels with the project) is the recommendation. A central app that lists many projects would read those files, or take them as uploads, and could later sync (see the sync project in the repo `BACKLOG.md`).
5. **Incremental ingest.** The spike recomputes everything each run (140 commits take a fraction of a second). For long histories, keep the last snapshot and the file table and continue from the last processed commit.

## Roadmap

- **Phase 0, the spike (done).** Importer for git, fork of the renderer, a player page, two groupings of this repo, notes. Acceptance: the Toolbox repo plays back as a growing, budding shape.
- **Phase 1, make it say something true.** Per-project `.crystal/areas.json`; the maturity ladder with the signals it reads; the inner shape from the ladder; a tooltip showing why an area has the rung it has; churn as a wobble. Acceptance: two or three real projects (this repo, one finished app, one half-built one) look different and look right to the person who built them.
- **Phase 2, per-session snapshots.** A Stop hook that appends a snapshot per session, with the session's area activity and AI-authored share; the importer merges them with git. Acceptance: a session that changed nothing in git still appears as a frame.
- **Phase 3, a gallery.** One small animated shape per project (the Toolbox cards could carry them as thumbnails, the way Facet's card has its animated logo), a compare view, and video export reusing Facet's exporter. Acceptance: the Toolbox home page shows a growth shape per tool.
- **Phase 4, more signals.** Tests, checklists, issues, deploys, manual sliders, semantic areas.

## Risks and honesty

- Lines and files are not progress. The picture should say what it is built from and never claim accuracy; the goal is the feeling of an idea growing to completion.
- One signal rarely tells the truth alone. The settled measure, for example, makes a quiet area look finished. Blend signals and show how.
- Bulk changes (a vendored folder, a generated file, a big import) distort size. The importer should ignore paths by config and the renderer should scale by square root or log.
- Renames and moves look like a delete plus an add. The spike turns git's rename detection off for simplicity; aliases cover the known cases, and `--find-renames` is the proper fix.
- A shallow clone gives a truncated history. The cloud sandbox used for this work was shallow (82 commits) until `git fetch --unshallow origin`. Any runner must check `git rev-parse --is-shallow-repository`.

## Open questions

1. Is "settled" worth keeping once the maturity ladder exists, or does it become only an input to it?
2. Should the areas be the same set for every project (a fixed template, so shapes can be compared) or per project? A fixed template of eight makes the shapes comparable at a glance, which the gallery wants.
3. How should AI-authored work show up: a separate colour in the ring, a second inner shape, or only in the tooltip?
4. Should an area ever shrink visibly (deleted code), or is the outline a high-water mark? Facet shrinks it; the spike shrinks it; a high-water mark may read better for "growth".
5. What is a "snapshot" for a human who does not use git (a design or writing project)? The manual slider and a timestamped check-in cover it; is that enough?
6. Where do the per-project files live when the repo is private and the viewer is a separate app?

## Running the spike

- Regenerate the data: `node tools/private/crystal/ingest/git-to-crystal.mjs --mode areas` and `--mode tools` (options: `--repo <path>`, `--settle <days>`, `--top <n>`, `--alias old=new`, `--out <file>`, `--name <text>`). The clone must not be shallow.
- View it: `npm run dev` from the repo root, then open `/crystal/` (add `?set=tools` for the by-tool grouping, `?paused=1` to start paused, `?u=0.5` to start halfway). `window.__CRYSTAL` has `seek(u)`, `play(on)` and the loaded data, for tests.

## Files in this folder

- `README.md` this scope, `FACET-CONTEXT.md` how it relates to Facet and where to look, `SPIKE-LOG.md` what was done and found, `info.md` the short write-up the site shows at `/crystal/info`, `meta.json` toolbox metadata (status concept, private).
- `index.html` the player page, `lib/shape-fork.js` the forked renderer, `ingest/git-to-crystal.mjs` the git importer.
- `data/toolbox-areas.json`, `data/toolbox-tools.json` generated data (committed so the page works without running anything), `data/README.md` the format.

## Glossary

- **Area / category / corner**: the same thing seen three ways (the rule that groups files; Facet's word for it; the point on the shape).
- **Outline / total**: how much exists. **Inner shape / sum**: how finished it is.
- **Settled**: not touched for N days. **Snapshot**: one moment in the data file.
- **Bud / fold**: a corner appearing out of the shape / disappearing back into it.
- **Presence**: a 0 to 1 weight per area that eases a corner in or out over at least 3% of the timeline.
