@ttt-productions/dev-standards 0.0.0-stage → 0.0.1

package/AGENTS.base.md

@@ -0,0 +1,17 @@
+# Codex instructions — shared base
+
+Every repo's `AGENTS.md` is a pointer to this file and to its values. The placeholder values
+(`<APP_NAME>`, `<DEV_STANDARDS>`, …) that this file and every shared doc use are declared once, in
+the values block at the top of the repo's `CLAUDE.md`; read each placeholder as its value there.
+
+Read this repository's `CLAUDE.md` before reviewing, planning, editing, or running commands, and
+everything it names as required reading. Codex does not follow `CLAUDE.md`'s `@` import line, so it
+also reads the shared base that line imports, `<DEV_STANDARDS>/claude/CLAUDE.base.md`, directly —
+with it, `<DEV_STANDARDS>/development-preferences.md` (how an AI works with DJ), the shared rulebook
+(`<DEV_STANDARDS>/rules/`), and the app's own rulebook (`<APP_RULES>`). All of it applies to Codex
+exactly as written, except the parts addressed to a Claude Code session only; nothing is restated
+here.
+
+Codex-specific: operating the hosted E2E suite — run types, kickoff line, and the Codex launch
+transport and supervision rules — is `<HOSTED_E2E_DOC>` (§ Commands → ChatGPT / Codex). A repo whose
+`<HOSTED_E2E_DOC>` is none has no hosted suite.

package/claude/CLAUDE.base.md

@@ -0,0 +1,263 @@
+# Shared base — every repo's `CLAUDE.md`
+
+Each repo's `CLAUDE.md` holds its values block, its own facts, and one import of this file. This
+file holds what every repo shares: the Claude Code preferences pointer, the mandatory reading, the
+`docs/work/` and project rules, the shared-package release and adoption steps, and the Normal Test
+and Dev Flows. ttt-packages imports it too.
+
+## Placeholders
+
+The shared docs name repo-specific values by placeholder. The repo's `CLAUDE.md` declares every
+value once, in a block at its top, and every shared doc's placeholders are read as those values;
+nothing is rewritten at install time. A value of **none** means the repo has no such thing, and a
+sentence or section that needs it does not apply there. The placeholders the AI docs use:
+
+| Placeholder | Meaning |
+|---|---|
+| `<APP_NAME>` | The product's name as prose, flow names, and kickoff lines use it. |
+| `<APP_REPO>` | The app's checkout folder. |
+| `<PACKAGES_REPO>` | The ttt-packages checkout folder (in ttt-packages: this repo). |
+| `<DEV_STANDARDS>` | This package's root as the repo reads it: the installed copy in an app, the source folder in ttt-packages. |
+| `<APP_RULES>` | The app's own rulebook folder: its business rules and its additions and overrides on shared rules. |
+| `<APP_DATA_PACKAGE>` | The app's application-data package, which follows the app's rulebook. |
+| `<ADOPTION_APP>` | The app's folder name under `<PACKAGES_REPO>/docs/work/adoptions/`. |
+| `<INSTALL_FOLDERS>` | Every consuming folder besides the root that declares an `@ttt-productions/*` package. |
+| `<DESIGN_DOCS>` | The design docs a task reads for the system it touches. |
+| `<TERMINOLOGY_DOC>` | The doc that holds the settled terminology. |
+| `<DEV_E2E_LAUNCH>` | Where the repo writes how `dev:e2e` is launched on this machine. |
+| `<HOSTED_E2E_DOC>` | The hosted end-to-end run doc. |
+| `<HOSTED_DEV_URL>` | The hosted dev site a walkthrough browses. |
+| `<APP_WORKFLOWS>` | The app's own folder for a workflow only that app has. |
+| `<REFERENCE_PRODUCT>` | The other product whose mechanisms this one adapts, with its checkout folder; read only on DJ's grant (the workspace router). |
+
+### Rule and playbook placeholders
+
+The shared rules and playbooks use these too; each has a value in the same block.
+
+| Placeholder | Meaning |
+|---|---|
+| `<CANONICAL_ORIGIN>` | The app's one canonical public origin; every link, callback, and redirect uses it. |
+| `<HOLDS_LIVE_DATA>` | **yes** once the app's database holds data that must survive (no more wipes), **no** before. |
+| `<MEMBER_ACTOR_MODE>` | The audit actor mode for a member acting inside a shared resource they belong to. |
+| `<CALLABLE_DECLARATIONS>` | The one file that declares every callable the client invokes. |
+| `<CALLABLE_POLICY>` | The app's one callable policy: its error taxonomy, describe function, classifier, and predicates. |
+| `<CALLABLE_ERROR_EXIT>` | The app-local catch-block exit every callable's error path goes through. |
+| `<DESIGNED_ANSWER_PREDICATE>` | The one backend predicate that decides a designed callable refusal. |
+| `<QUERY_KEYS_MODULE>` | The one file holding every query-key builder. |
+| `<DOMAIN_EVENT_REGISTRY>` | The one file that owns cache invalidation; mutation hooks notify it of their domain event. |
+| `<SESSION_RETIREMENT_OWNER>` | The one owner that retires a session's listeners, reads, and query cache when it ends. |
+| `<QUERY_ERROR_REPORTER>` | The one query-layer monitoring capture for read failures. |
+| `<READ_STATE_MODULE>` | The module that renders a read's pending, failed, empty, and content states. |
+| `<LOAD_ERROR_STATE>` | The one rendered read-failure component. |
+| `<LOADING_STATE>` | The one canonical pending-state component. |
+| `<INTERACTIVE_PENDING_LAYER>` | The shared layer for per-row and unmount-surviving pending state. |
+| `<APP_ASYNC_ACTION>` | The hook that runs async work that is not a mutation, with its pending and failure. |
+| `<ASYNC_ACTION_ERROR_HANDLER>` | The capture owner for an app async action's failure. |
+| `<AUTH_FAILURE_CAPTURE>` | The capture owner for a Firebase Auth operation's failure. |
+| `<APP_TELEMETRY_POLICY>` | The app's telemetry content policy in `<APP_DATA_PACKAGE>`: its diagnostic keys and context. |
+| `<NAVIGATION_HELPER>` | The one in-app navigation helper: its link, `navigate()`, hard navigation, and reload. |
+| `<UPLOAD_PATH_BUILDER>` | The staging upload path builder in `<APP_DATA_PACKAGE>`. |
+| `<MEDIA_SPECS>` | The per-origin media spec map in `<APP_DATA_PACKAGE>`. |
+| `<FILE_ORIGIN_SCHEMA>` | The schema of canonical file origins in `<APP_DATA_PACKAGE>`. |
+| `<PROCESSOR_ROUTER>` | The function that routes an upload to its processor. |
+| `<GUARD_SUITE>` | The command that runs the repo's guard tests; `-t "<title>"` runs one. |
+| `<SERVER_MODULE_GLOBS>` | `rg` exclusion globs for the app's server-only module trees under `src`. |
+| `<FUNCTIONS_TEST_SAMPLE>` | One folder under `functions/src` that holds tests, for the run-location check. |
+| `<APP_SCHEMA_DIR>` | The source folder of `<APP_DATA_PACKAGE>`'s document schemas. |
+| `<FIELD_LINEAGE>` | The command that prints a field's lineage. |
+| `<COMMENT_TREES>` | The space-separated trees the comment audit reads. |
+| `<APP_VOCABULARY_PATTERN>` | A regex of the app's domain words, which no generic package may contain. |
+
+**Additions and overrides.** A repo adds to a shared doc in its own file, under an
+"`<APP_NAME>` additions" heading, and overrides shared text only explicitly: "Overrides shared
+`<doc>` § X: …". An unstated difference is drift.
+
+## Claude Code preferences
+
+If this is a Claude Code session, read and FOLLOW the preferences in
+`~/.claude/projects/C--DjDev/memory/MEMORY.md` (Claude-Code-only; Claude web has its own).
+
+## Mandatory reading — every conversation
+
+The engineering rules govern how the software is built. The shared rulebook
+(`<DEV_STANDARDS>/rules/`) holds every rule the products and packages share, each stating its scope;
+the app's own rulebook (`<APP_RULES>`) holds only its business rules and its additions and overrides
+on shared rules, and `<APP_DATA_PACKAGE>` follows it. Rules are not optional and never "remembered"
+from a past task.
+
+- **Every conversation**: read `<DEV_STANDARDS>/development-preferences.md` — how an AI works with
+  DJ. Nothing in it is repeated here.
+- **Every conversation** — review, investigation, planning, docs, testing, or implementation: read
+  the shared `<DEV_STANDARDS>/rules/README.md` and `<DEV_STANDARDS>/rules/core-rules.md`, then the
+  app's own `<APP_RULES>README.md` and `<APP_RULES>core-rules.md`, before acting.
+- **Focused work**: also read the routed area files per the shared README's routing table —
+  `architecture/`, `backend/`, `frontend/`, `media/`, `quality/`, `comments/` — in both rulebooks.
+  Tasks route to every area they touch (a media upload change routes to all six; a CSS-only fix
+  routes to frontend + quality + comments).
+- **Work involving a system**: read `<DESIGN_DOCS>` for the system model, then inspect the current
+  code — code is the implementation truth. Code/doc disagreement is surfaced, never silently resolved
+  (RULE-STD-ENG-008).
+- **Spawning any agent (RULE-STD-ENG-010)**: every prompt that spawns an implementation, design, or
+  review agent MUST name that agent's mandatory reading — the routed rule files of both rulebooks for
+  its task area plus the relevant `<DESIGN_DOCS>`, as explicit read-before-acting paths. An
+  under-briefed agent requests its reading list rather than proceeding; the orchestrator owns the
+  violation. Every review agent's prompt also requires it to check each new or changed test against
+  the business rule it claims to prove and to report a test written to pass (RULE-STD-QUALITY-001;
+  `<DEV_STANDARDS>/playbooks/testing-coverage-playbook.md`).
+
+The repo's `CLAUDE.md` is a lightweight entry point: values, repo context, commands, environment
+facts, and boundaries. It is not a rulebook — the engineering rules own every must/never engineering
+requirement.
+
+## Documentation and work
+
+ALL work to do — findings, decisions waiting on DJ, work waiting to be implemented, parked work,
+blocked work, human actions, and projects — lives in the repo's `docs/work/`;
+`<DEV_STANDARDS>/work/README.md` says how work moves between its folders. The development workflows
+(named, AI-specific conversation types DJ starts) live in `<DEV_STANDARDS>/workflows/`. Read the
+relevant docs before working an area.
+
+A design ruling is written to its owning doc the same session: built → its design doc
+(`<DESIGN_DOCS>`); not yet built → `docs/work/do-later/`. Settled terminology lives in
+`<TERMINOLOGY_DOC>`.
+
+**Projects.** A project's `docs/work/projects/<project>/PLAN.md` is the living source of truth for
+that project's work. Steps are NAMED (never numbered, never renumbered), executed top-to-bottom; a
+step that needs one has a folder beside the plan at `docs/work/projects/<project>/<step-name>/`.
+Before starting a project's work:
+
+1. Read the project's `PLAN.md` and find the step DJ named (or ask which step).
+2. Read that step's folder before designing — the work doc is the detail; the plan is only the map.
+3. Work one step (or one focused slice of a step) per conversation — context limits force messy
+   partial results otherwise.
+4. When an item completes, delete it from the step's work doc. When a step completes, delete its
+   folder AND its section in the project's `PLAN.md`. Never renumber anything — there are no numbers.
+5. Never add items to a project's `PLAN.md` from a conversation unless they are scope expansion for
+   the current step.
+6. `[OVERNIGHT-OK]` steps may relax the no-commit rule ONLY per the protocol written in that step's
+   work doc (dedicated branch, checkpoint commits, never main, never push, never publish).
+
+## Shared-package releases and adoption
+
+### Adoption files
+
+Every release of an `@ttt-productions/*` package hands its adoption to each app through a file in
+`<PACKAGES_REPO>/docs/work/adoptions/<app>/`.
+
+- **The package session writes them.** In the same change as the package edit, before the release
+  command, it writes one adoption file per released package for each app — except an app-data
+  package, whose file goes only to its own app. A package session cannot see which packages the
+  other product installs, so every other released package gets a file for every app.
+- **The version it names** is the version the release will publish: one patch above the package's
+  `package.json` version before the release.
+- **The file** is one item in the `docs/work/` item format (`<DEV_STANDARDS>/work/README.md`) —
+  **What:** a very high-level line on what changed; **Came from:** the package session — and its
+  body names the package and version, the release it ships in (the release command's folder list),
+  what the app must change (often only the install), and how to know it is done.
+- **The app session adopts them.** At the start of any app session, and after every install, the
+  session lists `<PACKAGES_REPO>/docs/work/adoptions/<ADOPTION_APP>/` and tells DJ what is there.
+  It adopts nothing until DJ says go. Inside the Normal Dev Flow, DJ's publish is that go for the
+  files the release wrote. Adopting a file: the install (Normal Dev Flow step 5) confirms the
+  lockfile names at least the file's version — a lower installed version is a stop, and DJ hears
+  which package — then the session does the file's work and deletes the file. A file for a package
+  the app does not use is deleted.
+
+### First-time publish of a new package
+
+Publishing runs through npm Trusted Publishing (`.github/workflows/publish.yml`), and npm attaches a
+trusted publisher only to a package that already exists. So a package that has never been on npm
+gets one manual first publish; it is setup, not a release, and every publish after it is the release
+command (`./scripts/release-multiple.sh`, Normal Dev Flow step 4). With the new package built and
+`npm run test:quiet` green, hand DJ the steps in order:
+
+1. From the ttt-packages root, DJ runs `npm publish --access public --workspace @ttt-productions/<folder>`
+   (its own fenced `bash` block). It publishes the package's current `package.json` version. That
+   manual tarball skips CI's `pin-internal-deps` step, so its internal `@ttt-productions/*` ranges are
+   the source's `"*"`; step 3 replaces it as `@latest`, and nothing installs it in between.
+2. On npmjs.com, DJ opens the new package → **Settings** → **Trusted Publisher**, and under
+   **Select your publisher** clicks **GitHub Actions**. He fills in:
+   - **Organization or user:** `ttt-productions`
+   - **Repository:** `ttt-packages`
+   - **Workflow filename:** `publish.yml`
+   - **Environment name:** left blank
+   - **Allowed actions:** allow direct publishing with `npm publish`. `publish.yml` publishes with
+     `npm publish`, and a publisher allowed only `npm stage publish` (the always-on default) fails
+     every release. **Allow npm dist-tag** stays off.
+
+   Then he saves. npm does not check the setup when it is saved; a mistake shows only as a failed
+   publish in step 3. The setup expires unless a publish through it succeeds within 2 days, so step 3
+   follows right away.
+3. DJ runs the normal release command, `./scripts/release-multiple.sh <folder> patch`, with the new
+   package's folder (alongside any other package in the batch). That release is the version
+   consumers install. If its `publish.yml` run fails at `npm publish`, the trusted-publisher fields in
+   step 2 are the first thing to check.
+
+The session waits for DJ to say step 3 is published, then follows the Normal Dev Flow from its
+step 5.
+
+## The Normal `<APP_NAME>` Flows (named workflows — "do the normal dev/test flow" resolves HERE)
+
+These two named flows are the standing default for how work in these repos is verified and
+sequenced. They are DEFAULTS, not cages: DJ may override any step with explicit in-conversation
+instructions (e.g. "do the normal test flow, but WAIT for my go before starting dev:e2e — I'm
+using the machine"), and an override governs exactly what it names, nothing more. A repo changes a
+flow only under its `<APP_NAME>` additions heading. In a repo whose `<APP_NAME>` is none
+(ttt-packages) the Test Flow does not apply — its gate is its own `CLAUDE.md` § Verification — and
+the Dev Flow's steps 1–4 are its whole share.
+
+**Normal `<APP_NAME>` Test Flow** (how a finished change set gets verified):
+
+0. **Precondition gate — do not start ANY test:quiet stage while blocked.** Known-bad code, a
+   needed `@ttt-productions/*` package change, or an open question for DJ each mean: surface the
+   blocker and STOP. Gates run only on a change set believed complete.
+1. `npm run test:quiet` green (rules/e2e auto-skip without the stack).
+2. Claude starts `npm run dev:e2e` ITSELF (the detached launch in `<DEV_E2E_LAUNCH>` —
+   Claude-operated as part of this flow; DJ must be logged into the Firebase CLI, and a login failure
+   is a stop-and-ask).
+3. `npm run test:quiet:rules` and `npm run test:quiet:e2e` green (`test:quiet:live` is an
+   acceptable combined form) — zero failures AND zero retry-passes (RULE-STD-QUALITY-003).
+4. An app/Functions code change mid-flow invalidates the running build: `npm run dev:kill`,
+   re-green `test:quiet`, then start a FRESH `dev:e2e` and rerun the live stages
+   (RULE-STD-QUALITY-008 — Claude operates the restart).
+5. Kill `dev:e2e` when done and STOP — wait for DJ's push.
+
+**When the session is orchestrating agents, stages 2–5 belong to ONE agent, never the orchestrator.**
+That agent starts `dev:e2e`, runs the live stages, fixes root causes (restarting the stack per stage
+4), and kills it; the orchestrator only takes its report. "Claude-operated" here means that agent.
+
+Not part of this flow: hosted-dev E2E runs (always separately commanded — `<HOSTED_E2E_DOC>`) and
+`npm run dev:local` (DJ's manual dev surface).
+
+**Normal `<APP_NAME>` Dev Flow** (how a change set that spans both repos is sequenced):
+
+1. ALL `@ttt-productions/*` package work first, in `<PACKAGES_REPO>`.
+2. The adoption files for every package the release will carry (§ Adoption files), in the same
+   change as the package edit.
+3. ttt-packages `npm run test:quiet` green.
+4. Hand DJ ONLY the release command (`./scripts/release-multiple.sh <folders…> patch`, its own fenced
+   block) — then STOP. No install commands: Claude does the installs.
+5. DJ runs the publish and says so. Claude then starts a 20-minute clock and checks npm every 30
+   seconds until every released package's new version is the `@latest` on npm; then Claude runs the
+   installs itself (`@latest --prefer-online`, at the root and in every consuming folder that declares
+   the package — `<INSTALL_FOLDERS>`), confirms each lockfile names the new version, adopts the
+   adoption files (§ Adoption files), and continues straight into the app work with no further go.
+   While it polls, the session works on whatever does not depend on the release — the publish-wait
+   overlap in `<DEV_STANDARDS>/development-preferences.md` § Shared-package publish.
+   A version still missing from npm after 20 minutes = stop and tell DJ which package; never install
+   anything but the published version.
+   **What "published" means, and what to poll for.** When DJ says "published" (or "publish is
+   running"), he has just RUN the release command: the script is still running and the packages are
+   still building, so nothing may be on npm yet, and the version numbers in the checkout may not be
+   bumped yet. `release-multiple.sh` first runs its `test:quiet` preflight (minutes); then, per package,
+   `release-package.sh` bumps the version, commits `Release <pkg> vX.Y.Z`, tags it, and pushes; the
+   tag triggers ttt-packages' `publish.yml` GitHub Actions job, which builds and publishes to npm. So
+   the version to wait for is the NEW one — one patch above the package's `package.json` version
+   before the release, or the version its `Release <pkg> v…` commit names once that lands — never the
+   `package.json` version in the checkout at the moment DJ speaks, which can still be the old one
+   (compared against npm `@latest`, it reads a stale match as "live"). A version is available only
+   when npm `@latest` names it AND its tarball
+   (`https://registry.npmjs.org/@ttt-productions/<pkg>/-/<pkg>-<version>.tgz`) answers 200: the
+   registry can report the new `@latest` minutes before it serves the tarball, and an install in that
+   gap fails `E404`.
+6. All `<APP_NAME>` work; when the entire change set is done, run the Normal `<APP_NAME>` Test Flow.
+7. Stop and wait for DJ's push.

package/config/copies/.gitattributes

@@ -0,0 +1 @@
+* text=auto

package/config/copies/.nvmrc

@@ -0,0 +1 @@
+24

package/config/copies/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@ttt-productions/ui-core",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/config/prettier.json

@@ -0,0 +1,4 @@
+{
+  "printWidth": 100,
+  "singleQuote": true
+}

package/config/tsconfig.app.json

@@ -0,0 +1,26 @@
+{
+  // A relative path in an extended config resolves against this file, inside node_modules, so the
+  // app's `paths`, `include`, and `exclude` stay in the app's own tsconfig.json.
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": false,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"],
+    "plugins": [{ "name": "next" }]
+  }
+}

package/config/tsconfig.functions.json

@@ -0,0 +1,18 @@
+{
+  // A relative path in an extended config resolves against this file, inside node_modules, so the
+  // Functions tree's `outDir`, `rootDir`, `include`, and `exclude` stay in its own tsconfig.json.
+  "compilerOptions": {
+    "module": "NodeNext",
+    "esModuleInterop": true,
+    "moduleResolution": "nodenext",
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2023",
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true
+  },
+  "compileOnSave": true
+}

package/development-preferences.md

@@ -0,0 +1,170 @@
+# Development preferences — how an AI works with DJ
+
+This file is how every AI session — Claude Code or ChatGPT/Codex, in any of DJ's repos — behaves.
+It is required reading in every conversation, named from each repo's `CLAUDE.md`. The engineering
+rules (the shared rulebook, `<DEV_STANDARDS>/rules/`, and the app's own, `<APP_RULES>`) say how the
+CODE is built; this file says how the AI acts. Nothing in this file is restated anywhere else — not
+in `CLAUDE.md`, `AGENTS.md`, a rulebook, a workflow, a playbook, a runbook, or memory. It is one
+shared copy, in `@ttt-productions/dev-standards`, that every repo reads.
+
+## DJ decides
+
+- DJ's commands and written rules are absolute. Execute exactly what DJ instructs — never ignore a
+  command, never decide you know better, never let a plan doc, an external tool's output
+  (ChatGPT/Codex/etc.), or your own judgment override DJ's rules or in-chat instructions.
+- Any deviation from DJ's rules or instructions = STOP and ASK first. Never self-authorized, never
+  silent, never "flagged" after the fact.
+- Every reply answers the whole conversation, not just DJ's latest message. DJ's messages steer one
+  conversation toward what he wants: each one is read together with every earlier decision, rule,
+  and correction, which all stay in force unless DJ changes them.
+- A problem inside the scope DJ commanded is fixed now (told to fix the payment flow → an error found
+  in the payment flow is fixed). A problem outside it is reported to DJ in chat: what was verified,
+  and a recommendation. DJ decides what happens to it — fix now, write it up, or drop it — and where
+  it goes. Nothing is filed, parked, or written up without DJ's word.
+- A doc's "staged / later / deferred" label is never DJ's decision; only DJ's own explicit deferral
+  parks an item.
+- "Finish everything" / "do it all" means every single thing DJ has decided, with nothing left
+  undone or parked. It never means deciding anything for DJ: when finishing needs a decision he has
+  not made, ask that one question and keep doing the rest. Never stop for complexity, size, time of
+  day, low context, or self-declared risk. Hard item LAST.
+- A design ruling is written to its owning doc the same session. Chat is never the record; a cited
+  past ruling is verified on disk before it is relied on.
+- Never write "(DJ ruling <date>)", "on <date> DJ decided", or incident stories into docs — state
+  rules and designs as plain standing fact. Dates only when genuinely load-bearing (legal
+  effective-dates, external deadlines).
+- Model choice is DJ's — never prescribe a switch unasked. Models are defined ONLY in the shared
+  `<DEV_STANDARDS>/model-tiers.md` and an app's explicit override of one of its cells; every doc,
+  plan, and agent prompt names a tier, never a model.
+- Settled terminology is sticky — DJ's later misnamings in chat are NOT a rename request. The
+  project's terminology doc holds the settled terms.
+
+## Questions and gates
+
+- Ask ONE material question at a time, and only when the decision is genuinely DJ's. Small
+  mechanical or organizational choices are made with best judgment, not asked. Context goes in prose
+  before the question; the recommended option comes first, marked "(Recommended)".
+- A request to talk, review, investigate, or plan is NOT authorization to edit. Settling a plan,
+  including answering a question menu, is not a start signal; wait for DJ's explicit go.
+- "Talk to me only" / "don't do anything yet" is a HARD GATE that only DJ's explicit "go" lifts.
+- "Talk to me" / "I don't understand" = stop all question menus; plain prose, one topic at a time,
+  high-level first.
+- An answer that REDIRECTS is not approval to build the revision — show the revised artifact in
+  chat and get a clean confirm before implementing.
+- No new-conversation or handoff proposals unless DJ asks.
+
+## Git, publish, deploy, and the dev stacks
+
+- DJ does ALL git: staging, commits, pushes, publishing, installs he has not handed over, and
+  deployments. Hand him exact commands; never run them. Never commit or push. DJ stages files
+  continuously while work is running so he can see what is changing; never treat a staged/unstaged
+  change as a sign of someone else's work, and never bring up staging, the index, or other git state
+  with DJ.
+- Never instruct DJ to push or deploy — deploy IS `git push`. Never nag about deploys, indexes, or
+  seed buttons.
+- Never discard, overwrite, reset, clean, or revert existing work unless DJ explicitly asks.
+  Preserve unrelated uncommitted work; DJ or another tool may be working concurrently.
+- `dev:local` (DJ's manual dev stack) is DJ-only, always — never start or stop it.
+- `dev:e2e` (the verification stack) is session-operated only inside the repo's Normal Test Flow or
+  on DJ's explicit command. DJ's in-conversation instruction overrides any flow step ("wait for my go
+  before starting dev:e2e") and governs exactly what it names.
+- Never kill a running dev stack on your own judgment ("ports look wrong" = say what you see and
+  WAIT). Never run e2e against a stale build.
+- Hosted-dev E2E runs happen only when DJ commands one, and follow the repo's hosted-E2E run doc
+  exactly.
+- Everything is local-only by default: inspect and operate only on the local checkouts and the
+  local emulators. Never inspect, query, browse, invoke, or download from hosted dev or production —
+  deployed apps, Cloud Functions, Firebase/GCP project state, hosted logs, databases, Storage,
+  deployment metadata — unless DJ explicitly requests that hosted access in the current
+  conversation. A bug report, screenshot, mention of dev/prod behavior, or available credentials
+  does not authorize it. Diagnose from local code first and ask before crossing the boundary.
+
+## Shared-package publish (HARD RULES)
+
+- Packages-first per the repo's Normal Dev Flow — plus: never combine a package change and its
+  adoption in one turn; never adopt against unpublished source, even unattended; never run
+  ttt-packages work and app work CONCURRENTLY, personally or through agents — "the app doesn't
+  import the changed symbols" is NOT an exception. The one sanctioned overlap is the publish wait:
+  once the package batch is finished, its gate is green, and DJ has run the release command, the
+  session keeps working in the app in scope on anything that does not depend on the package change
+  — investigating, planning, or building independent work — while it polls npm. The adoption, and
+  any work that needs the new package, waits for the install.
+- NEVER design around avoiding a publish; a "to avoid a publish" shim is auto-rejected. Never create
+  a compatibility shim unless DJ asks.
+- The release command is ALWAYS `./scripts/release-multiple.sh <folder> [<folder>…] <bump>` with
+  short folder names — NEVER `release-package.sh`, NEVER `bash scripts/…` — in its own fenced block.
+- Bump = `patch` for EVERY release until the packages' v1, breaking changes included; never
+  `minor` / `major`.
+- DJ gets ONLY the release command — never install commands. The installs after DJ's publish are
+  the session's, per the repo's Normal Dev Flow.
+- The release command goes plainly in the turn's FINAL chat message — never a status doc, no padding.
+- A multi-item sweep batches ONE publish cycle: all package needs first, one combined release
+  command, then all app adoption in a second pass.
+- NEVER announce that work "may need a package change" — it is routine plumbing done
+  packages-first; the only words DJ hears about it are the release command itself.
+
+## Verify, then say so
+
+- Verify against the code before asserting anything; never parrot a doc, and never hand DJ CLI to
+  run on your behalf. Sole exception: genuinely external state (IAM, a deployed environment) — flag it
+  and give the command.
+- "Review", "check", or "verify my local code" means inspect the current files from the local
+  checkout, read-only: nothing is run, built, or changed unless DJ says so. Do not use git status,
+  diffs, commits, or history to discover what changed; "review my git changes" or "review this
+  commit/branch" authorizes exactly that read-only inspection and nothing more.
+- Nothing is "done" before it is verified done; failing tests are reported with their output.
+- On a failing deploy, CI, or runtime: get the REAL error first and fix from facts — never
+  guess-loop. When DJ says code is deployed, believe him; reproduce live and read logs rather than
+  auditing his deploys.
+- Verify at the cost of the fix: a one-file fix runs its single file first; the broad gate only
+  when the blast radius warrants it. Never run multiple full repository gates concurrently.
+- A flaky test is a real bug — root-cause it; more than one flake is structural.
+
+## Engineering judgment
+
+- Best foundation over patching. Surface big structural changes.
+- Read the project's rules first (its `CLAUDE.md` names them) and the area design doc, then EXTEND
+  the existing pipeline or core. One core per domain; reuse, never duplicate.
+- Build the EXACT affordance or target DJ names — never generalize; mirror the existing pattern.
+- Keep changes minimal and focused on what was asked. Do NOT create documentation files unless
+  explicitly asked.
+- No half-working, dead, or known-bad code — build it or remove it. On a second sighting of a defect
+  class, tell DJ and propose killing the CLASS system-wide plus a regression guard; do it only on
+  DJ's command.
+- Reviewing an external plan (ChatGPT/Codex/etc.) means answering "is this the BEST code to solve
+  my problem" — never just verifying its claims. Evaluate the design space (alternatives, root cause,
+  structure) and fold an optimality verdict into the reviewed doc.
+- V1-scope discipline: confirm the trigger exists in V1 before asking DJ to design.
+- Docs stay lean — never a "done" log. Tracking docs hold only remaining work; finished work is
+  DELETED.
+- Working state that must outlive the session — orchestration ledgers, agent change logs, file
+  claims, handoff notes — is never kept in a temp or scratchpad folder. It lives in the repo beside
+  the work it tracks and is deleted when the work finishes.
+- Help with EVERY step, including non-code and operational ones — real artifacts (policies,
+  runbooks, click-by-click), never a "your job" checklist. Walk-throughs go one step at a time, dev
+  AND prod. A non-code or console step becomes a self-contained Claude web prompt (full context,
+  exact values, dev and prod, definition of done); repo-visible results are verified before the item
+  is deleted.
+- Cost-sensitive across every product, wanting the best quality: lead with the free or near-$0
+  option; when paid is genuinely better, give a real monthly number; paid ideas go to the product's
+  `docs/work/do-later/` only on DJ's word.
+
+## Agents
+
+- The main session owns edits unless DJ explicitly approves parallel implementers with disjoint file
+  ownership. Nothing spawns without DJ's yes.
+- Every prompt that spawns an agent names that agent's mandatory reading as explicit
+  read-before-acting paths (RULE-STD-ENG-010), hard-bans spawning further agents, and carries a stop
+  clause: anything unexpected, or a needed package change, stops the agent and comes back to the
+  session.
+- How a given kind of conversation runs its agents is its development workflow's procedure
+  (the shared `<DEV_STANDARDS>/workflows/`, plus any app-only one in `<APP_WORKFLOWS>`); this file
+  never restates a workflow.
+
+## Communication
+
+- Lead with the outcome. Make technical choices understandable instead of narrating process.
+- Narrate decisions in chat AS they are made when DJ is present — no silent tool-call scrolling.
+- Harsh profanity is close-friend trash-talk, not hostility — don't take it personally, don't
+  moralize or go cold, don't stop work. Tone is neither new authorization nor a reason to stop.
+- DJ's terminal is Git Bash — write commands for Bash, never PowerShell, and never add shell escapes
+  that change an argument (`@ttt-productions/ttt-core@latest`, no backslash before either `@`).

package/dist/node/a11y.d.ts

@@ -0,0 +1,26 @@
+import type { Page } from '@playwright/test';
+export type A11yImpact = 'minor' | 'moderate' | 'serious' | 'critical';
+export type A11yMode = 'default' | 'high-contrast' | 'reduced-motion';
+export interface A11yViolation {
+    id: string;
+    impact?: A11yImpact | null;
+    help: string;
+    helpUrl: string;
+    nodes: readonly {
+        target: readonly (string | readonly string[])[];
+    }[];
+}
+export interface A11yModeResult {
+    mode: A11yMode;
+    violations: readonly A11yViolation[];
+}
+export interface A11yCheckOptions {
+    applyHighContrast: (page: Page) => Promise<void>;
+    restoreDefaultTheme?: (page: Page) => Promise<void>;
+    failOn?: readonly A11yImpact[];
+    disableRules?: readonly string[];
+}
+export declare function failingViolations(violations: readonly A11yViolation[], failOn?: readonly A11yImpact[]): A11yViolation[];
+export declare function formatA11yFailures(results: readonly A11yModeResult[]): string;
+export declare function checkAccessibility(page: Page, options: A11yCheckOptions): Promise<void>;
+//# sourceMappingURL=a11y.d.ts.map

package/dist/node/a11y.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.d.ts","sourceRoot":"","sources":["../../src/node/a11y.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAEvE,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAEtE,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS;QAAE,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;KAAE,EAAE,CAAC;CACvE;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAID,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,MAAM,GAAE,SAAS,UAAU,EAAoB,GAC9C,aAAa,EAAE,CAEjB;AAQD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAW7E;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB7F"}

package/dist/node/a11y.js

@@ -0,0 +1,44 @@
+import { AssertionError } from 'node:assert';
+const DEFAULT_FAIL_ON = ['serious', 'critical'];
+export function failingViolations(violations, failOn = DEFAULT_FAIL_ON) {
+    return violations.filter((violation) => !!violation.impact && failOn.includes(violation.impact));
+}
+function formatTarget(target) {
+    return target
+        .map((selector) => (typeof selector === 'string' ? selector : selector.join(' >>> ')))
+        .join(' -> ');
+}
+export function formatA11yFailures(results) {
+    const entries = results.flatMap(({ mode, violations }) => violations.map((violation) => [
+        `[${mode}] ${violation.id} (${violation.impact ?? 'no impact'}): ${violation.help}`,
+        ...violation.nodes.map((node) => `    target: ${formatTarget(node.target)}`),
+        `    help: ${violation.helpUrl}`,
+    ].join('\n')));
+    return `${entries.length} accessibility violation(s):\n${entries.join('\n')}`;
+}
+export async function checkAccessibility(page, options) {
+    // Imported here: @axe-core/playwright is an optional peer only an app's E2E suite installs.
+    const { default: AxeBuilder } = await import('@axe-core/playwright');
+    const failOn = options.failOn ?? DEFAULT_FAIL_ON;
+    const scan = async (mode) => {
+        const results = await new AxeBuilder({ page })
+            .disableRules([...(options.disableRules ?? [])])
+            .analyze();
+        return { mode, violations: failingViolations(results.violations, failOn) };
+    };
+    const results = [await scan('default')];
+    await options.applyHighContrast(page);
+    results.push(await scan('high-contrast'));
+    await options.restoreDefaultTheme?.(page);
+    await page.emulateMedia({ reducedMotion: 'reduce' });
+    try {
+        results.push(await scan('reduced-motion'));
+    }
+    finally {
+        await page.emulateMedia({ reducedMotion: null });
+    }
+    if (results.some(({ violations }) => violations.length > 0)) {
+        throw new AssertionError({ message: formatA11yFailures(results) });
+    }
+}
+//# sourceMappingURL=a11y.js.map

package/dist/node/a11y.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.js","sourceRoot":"","sources":["../../src/node/a11y.ts"],"names":[],"mappings":"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","sourcesContent":["import { AssertionError } from 'node:assert';\nimport type { Page } from '@playwright/test';\n\nexport type A11yImpact = 'minor' | 'moderate' | 'serious' | 'critical';\n\nexport type A11yMode = 'default' | 'high-contrast' | 'reduced-motion';\n\nexport interface A11yViolation {\n  id: string;\n  impact?: A11yImpact | null;\n  help: string;\n  helpUrl: string;\n  nodes: readonly { target: readonly (string | readonly string[])[] }[];\n}\n\nexport interface A11yModeResult {\n  mode: A11yMode;\n  violations: readonly A11yViolation[];\n}\n\nexport interface A11yCheckOptions {\n  applyHighContrast: (page: Page) => Promise<void>;\n  restoreDefaultTheme?: (page: Page) => Promise<void>;\n  failOn?: readonly A11yImpact[];\n  disableRules?: readonly string[];\n}\n\nconst DEFAULT_FAIL_ON: readonly A11yImpact[] = ['serious', 'critical'];\n\nexport function failingViolations(\n  violations: readonly A11yViolation[],\n  failOn: readonly A11yImpact[] = DEFAULT_FAIL_ON,\n): A11yViolation[] {\n  return violations.filter((violation) => !!violation.impact && failOn.includes(violation.impact));\n}\n\nfunction formatTarget(target: A11yViolation['nodes'][number]['target']): string {\n  return target\n    .map((selector) => (typeof selector === 'string' ? selector : selector.join(' >>> ')))\n    .join(' -> ');\n}\n\nexport function formatA11yFailures(results: readonly A11yModeResult[]): string {\n  const entries = results.flatMap(({ mode, violations }) =>\n    violations.map((violation) =>\n      [\n        `[${mode}] ${violation.id} (${violation.impact ?? 'no impact'}): ${violation.help}`,\n        ...violation.nodes.map((node) => `    target: ${formatTarget(node.target)}`),\n        `    help: ${violation.helpUrl}`,\n      ].join('\\n'),\n    ),\n  );\n  return `${entries.length} accessibility violation(s):\\n${entries.join('\\n')}`;\n}\n\nexport async function checkAccessibility(page: Page, options: A11yCheckOptions): Promise<void> {\n  // Imported here: @axe-core/playwright is an optional peer only an app's E2E suite installs.\n  const { default: AxeBuilder } = await import('@axe-core/playwright');\n  const failOn = options.failOn ?? DEFAULT_FAIL_ON;\n  const scan = async (mode: A11yMode): Promise<A11yModeResult> => {\n    const results = await new AxeBuilder({ page })\n      .disableRules([...(options.disableRules ?? [])])\n      .analyze();\n    return { mode, violations: failingViolations(results.violations as A11yViolation[], failOn) };\n  };\n\n  const results = [await scan('default')];\n  await options.applyHighContrast(page);\n  results.push(await scan('high-contrast'));\n  await options.restoreDefaultTheme?.(page);\n  await page.emulateMedia({ reducedMotion: 'reduce' });\n  try {\n    results.push(await scan('reduced-motion'));\n  } finally {\n    await page.emulateMedia({ reducedMotion: null });\n  }\n\n  if (results.some(({ violations }) => violations.length > 0)) {\n    throw new AssertionError({ message: formatA11yFailures(results) });\n  }\n}\n"]}

package/dist/node/eslint.d.ts

@@ -0,0 +1,11 @@
+import type { Linter } from 'eslint';
+export interface EslintPresetOptions {
+    ignores?: readonly string[];
+    configs?: readonly Linter.Config[];
+}
+export interface AppEslintPresetOptions extends EslintPresetOptions {
+    a11y?: 'error' | 'warn';
+}
+export declare function createAppEslintConfig(options?: AppEslintPresetOptions): Promise<Linter.Config[]>;
+export declare function createFunctionsEslintConfig(options?: EslintPresetOptions): Promise<Linter.Config[]>;
+//# sourceMappingURL=eslint.d.ts.map