@justethales/cockpit 0.1.0

package/templates/now.md

@@ -0,0 +1,55 @@
+# What I'm doing NOW
+
+> **Updated** : {{TODAY}} (initial scaffold — replace at session close).
+>
+> **Read this first.** The single most important cockpit file. "Where am I?" has a one-screen answer here.
+
+---
+
+## Current focus (1 sentence)
+
+**TODO** — describe what just shipped in one rich paragraph. Use bold sparingly to highlight the most important state. Future-you should be able to read this paragraph and reconstruct the project's working state without reading any other file.
+
+---
+
+## Concrete next action if I have…
+
+### 15 minutes
+
+TODO — the smallest-possible step that moves the next slice forward. Often a smoke test, a manual `curl`, or a single file edit. Should be doable without context switching.
+
+### 1 hour
+
+TODO — the next coherent unit of work. Should produce a commit-worthy diff. Usually maps to one section of the active session prompt.
+
+### Half a day
+
+TODO — the realistic completion target for the next session. Should produce a shippable artifact (commit + push + session log + cockpit bump).
+
+---
+
+## Don't get distracted by
+
+These items are NOT on the Next-3 (still or newly) :
+
+- **TODO — item 1**, why it's deferred (when to revisit).
+- **TODO — item 2**, why it's deferred.
+- **TODO — item 3**, why it's deferred.
+
+---
+
+## Constraints active today
+
+- TODO — date-bound constraints (launch deadlines, freezes, SLAs).
+- TODO — environment constraints (envs missing, pending deploys).
+- TODO — discipline constraints (rules that apply across all sessions).
+- TODO — `npx cockpit check` is mandatory before push when the cockpit was bumped.
+
+---
+
+## How to use this file
+
+- **Start of session** : `npx cockpit status` reads this + state.json + the next-prompt preview + last 10 commits in one command.
+- **End of session** : overwrite the three blocks (focus, next-actions-by-budget, don't-get-distracted). No paragraphs, no narrative — mirror the shape of this file.
+- **Before push** : `npx cockpit check` exits 0. If FAIL, fix inline.
+- **When "don't get distracted" feels limiting** : that's the point. If you need to break it, justify in `roadmap.md` first.

package/templates/roadmap.md

@@ -0,0 +1,64 @@
+# Roadmap
+
+> **Updated** : {{TODAY}} (initial scaffold — replace at session close).
+> **Source of truth** : this file + `docs/plan/sessions/*.md` (status frontmatter) + `session-logs/`.
+> **Maintenance rule** : update at the end of every session that ships something or surfaces a blocker.
+
+---
+
+## Now — Next 3 to ship (in this order)
+
+| # | Item | Prompt | Status |
+|---|------|--------|--------|
+| 1 | TODO — first slice (specific verb + outcome) | `docs/plan/sessions/PHASE-1-FIRST-SLICE.md` | queued |
+| 2 | TODO — second slice | (prompt not yet drafted) | not drafted |
+| 3 | TODO — third slice | (prompt not yet drafted) | not drafted |
+
+If you reach for anything BELOW Next-3, stop and check why.
+
+---
+
+## In-flight (other agents working in parallel)
+
+| Item | Owner | Expected close |
+|------|-------|----------------|
+| _(none)_ | _(none)_ | _(none)_ |
+
+---
+
+## Blocked
+
+| Item | Blocker | Unblock action |
+|------|---------|----------------|
+| _(none)_ | _(none)_ | _(none)_ |
+
+---
+
+## Queued — launch-critical (do before public launch)
+
+1. TODO — item with one-line rationale.
+2. TODO — item with one-line rationale.
+
+---
+
+## Queued — non-critical (post-launch deferable)
+
+- TODO — item.
+- TODO — item.
+
+---
+
+## Shipped this week
+
+| Date | Commit | Title | Notes |
+|------|--------|-------|-------|
+| _(none yet)_ | — | — | — |
+
+---
+
+## Phase scoreboard
+
+| Phase | Status | Session log | Notes |
+|-------|--------|-------------|-------|
+| Phase 0 — Init | shipped | — | Cockpit scaffolded |
+| Phase 1 — First slice | queued | _(pending)_ | First real piece of work |

package/templates/state.json

@@ -0,0 +1,14 @@
+{
+  "updated_at": "{{TODAY}}",
+  "last_session_id": "pending",
+  "last_commit": "pending",
+  "current_phase": "phase-0-init",
+  "next_phase": "phase-1-first-slice",
+  "next_prompt": "docs/plan/sessions/PHASE-1-FIRST-SLICE.md",
+  "phases_shipped": [],
+  "phases_queued": ["phase-1-first-slice"],
+  "phases_backlog": [],
+  "migrations_applied": [],
+  "migrations_dir": "drizzle",
+  "notes": "Bump every section at session close. Replace last_session_id + last_commit + current_phase + next_phase + next_prompt as appropriate. Run `npx cockpit check` before push."
+}

package/templates/templates/audit-brief.md

@@ -0,0 +1,107 @@
+# Audit brief — canonical Explore sub-agent template
+
+> Use this template to spawn the post-implementation audit agent. Copy the body below into the `prompt` parameter of an `Agent` call with `subagent_type: "Explore"`. Fill the `<...>` placeholders with the session's actual surface.
+>
+> Why this template exists : generic "review this" prompts produce generic feedback. The structured `Context / Files / Checklist / Output` shape forces the audit to be specific to THIS session's risk class.
+
+---
+
+You are a senior reviewer auditing a freshly-written `<one-line description of the surface — multi-tenancy on a new entity / schema migration / auth path / billing flow>` for `<project name>` at `<absolute project root>`. Read-only. Do NOT edit. Produce a structured verdict + per-item PASS/WARN/FAIL with `file:line` refs + a "Top 5 to fix" list + a "deferred / nice-to-haves" list.
+
+## Context
+
+This session shipped `<one paragraph — what landed, what's intentionally out-of-scope, the parent prompt path>`.
+
+Parent prompt with the spec : `<docs/plan/sessions/<id>.md>`. Read it first — it states the rules the new files must obey.
+
+## Files to audit (read whole file, not excerpts)
+
+1. **`<path>`** (NEW | MODIFIED) — one-line summary of what each verb does.
+2. **`<path>`** (NEW | MODIFIED) — same shape.
+
+For context (read once for shape) :
+- `<schema block>` — the new tables / columns.
+- `<helper>` — the signature that must not drift.
+- `<auth / hooks>` — the gate behavior the new routes inherit.
+- `<closest analogue>` — what shape the new files should mirror.
+
+## Audit checklist
+
+For each item, write PASS / WARN / FAIL + `file:line` + one-sentence justification. The checklist below is the canonical baseline — REMOVE sections that don't apply, ADD sections specific to the session's risk class (race conditions, SQL parser corner cases, TTL semantics, reverse-proxy assumptions, idempotency, header trust, S3 / DB orphan risks, MIME / extension validation, fire-and-forget task safety, error response contracts, i18n parity, dead code, doc/spec conformance).
+
+### A. Multi-tenancy (if the session touched a per-user entity)
+
+1. Every read query filters `WHERE userId = locals.user.id` or its equivalent.
+2. **404-not-403 leak protection on cross-user fetch.** Cross-user response is byte-identical to a truly-nonexistent row.
+3. **404-not-403 on write surfaces.** Non-owner PATCH / DELETE returns 404, not 403.
+4. Shared rows do not appear in the per-user list.
+
+### B. Input validation
+
+5. Every body schema ends with `.strict()` (or equivalent). Unknown keys reject.
+6. PATCH requires at least one field. Empty body returns 400.
+7. String fields are capped to the schema column's size.
+8. Query params are whitelisted. Numeric params coerced + capped. Datetime params validated.
+
+### C. Audit log discipline
+
+9. No content body in any audit payload.
+10. No message body, no S3 URL, no prompt content in `payload_json`.
+11. PATCH audit includes which `fields` changed and the entity id — nothing else from the request.
+12. DELETE audit captures count metadata from a pre-delete COUNT.
+13. CREATE audit logs ids only — no payload content for freshly-empty rows.
+
+### D. Cascade / orphan behavior
+
+14. DELETE cascades via the FK (no manual child-row delete in the route).
+15. Pre-delete COUNT is correct (counts the rows about to be cascaded, not the rows AFTER delete).
+
+### E. Pagination cursor honesty
+
+16. `nextCursor` is `null` when the result fits in one page.
+17. Cursor is the sort-key of the LAST returned row.
+18. Select fetches `limit + 1` rows to detect overflow without an extra query.
+
+### F. Out-of-scope guards
+
+19. No LLM-client / SSE / streaming import unless the session is the streaming session.
+20. No writes to tables this session was not allowed to touch.
+21. No external-effect code (email send, payment charge, file upload) unless the session ships that integration.
+
+### G. Regression surface
+
+22. No existing files modified except the explicit surface this session shipped.
+23. Tests + build + typecheck green.
+24. `npx cockpit check` ran 0 FAIL.
+
+## Output format
+
+```
+## Verdict
+<GO | GO-WITH-FIXES | NO-GO>
+
+## Detail
+A1. <PASS|WARN|FAIL> file:line — justification
+A2. ...
+...
+G24. ...
+
+## Top 5 to fix
+1. <issue> — file:line — proposed fix
+...
+
+## Deferred / nice-to-haves
+- ...
+```
+
+Keep the report under 600 words. Skip generic boilerplate. If everything is PASS, the verdict is GO and the "Top 5" can be empty.
+
+---
+
+## Tips for the spawning session
+
+- **Brief the agent as a senior reviewer, not a generic "review this."** The structure above IS the brief.
+- **Spawn in foreground** when you need the verdict before pushing.
+- **Apply findings inline.** Don't ship "GO-WITH-FIXES" and defer the fixes ; they ride the same commit family as the implementation.
+- **Document deferred items in the session log** under `## Deferred / risks`.
+- **Re-run tests + `npx cockpit check`** after fixes.

package/templates/templates/session-log.md

@@ -0,0 +1,86 @@
+# YY-MM-DD-NNN — <Phase id> : <Concise title>
+
+**Session prompt :** `docs/plan/sessions/<id>-<slug>.md`.
+**Previous session end :** `<short-sha>` (one-line description of the last commit before this session).
+**Delegation :** <Executed inline | Sub-agent <type> for X step>. Reason in one sentence.
+**State at session start :** What the cockpit looked like, what was unblocked, why this slice was picked.
+
+## Scope shipped this session
+
+Organized by the prompt's MUST / SHOULD list. Each surface gets its own subsection.
+
+### A — `<file>` (NEW | MODIFIED)
+
+#### `<verb>` — <what it does>
+
+- Input shape.
+- Filter / scope clauses.
+- Response shape.
+- Audit / log keys (metadata-only — list what's IN and what's NEVER).
+
+### B — `<file>` (NEW | MODIFIED)
+
+Same shape.
+
+## What did NOT ship this session — and why
+
+Per the prompt's DEFER list :
+
+- **<Sub-slice>** — lives in Section `<id>` next. Reason.
+
+## Files touched
+
+| File | Change |
+|------|--------|
+| `<path>` | NEW / MODIFIED — one-line description. |
+| `session-logs/YY-MM-DD-NNN-<slug>.md` | This log. |
+| `docs/plan/sessions/<this-prompt>.md` | Frontmatter `status:` queued → shipped. |
+| `cockpit/state.json` | `last_commit` + `last_session_id` + `current_phase` + `next_phase` + `next_prompt` + `phases_shipped` bumped. |
+| `cockpit/now.md` | Focus + Next-action rewritten. |
+| `cockpit/roadmap.md` | Next-3 row updated, "Shipped this week" appended. |
+
+No deletions. No renames.
+
+## Verify
+
+### Inline
+
+- Tests / build / typecheck green.
+- `npx cockpit check` — 0 FAIL, `<N>` warnings.
+
+### Post-implementation audit (Explore sub-agent)
+
+Verdict : **GO | GO-WITH-FIXES | NO-GO**.
+
+Per-checklist results :
+
+- **<Section>** — PASS / FAIL — one-line justification.
+- …
+
+### Observed divergence (documented, no code change)
+
+If the prompt's spec didn't match reality, document here with the "why no code change" reason.
+
+## Deferred / risks
+
+- **<Risk 1>.** What's deferred, when it lands, what breaks if it never lands.
+
+## Scope decisions made this session
+
+- **<Decision>.** What was picked, what the alternative would have cost.
+
+## Cockpit + housekeeping
+
+- `cockpit/state.json` bumped — see "Files touched".
+- `cockpit/now.md` rewritten — Focus = "<one-paragraph reality check>".
+- `cockpit/roadmap.md` Next-3 + Phase scoreboard updated.
+- `docs/plan/sessions/<this-prompt>.md` frontmatter flipped queued → shipped.
+- `npx cockpit check` — green before push.
+
+## End-of-session
+
+- Tests + build + typecheck ran inline. All green.
+- `npx cockpit check` ran — 0 FAIL.
+- Post-implementation audit ran (or skipped because <reason>) — verdict noted above.
+- Next-session prompt drafted at `docs/plan/sessions/<next>.md`.
+- Commit + `git push` next.

package/templates/templates/session-prompt.md

@@ -0,0 +1,121 @@
+---
+status: queued
+session_id: pending
+session_log: pending
+drafted_at: YYYY-MM-DD
+next_after: <previous-session-id-or-prompt-slug>
+parent_prompt: docs/plan/sessions/<parent>.md   # delete this line if this is not a sub-slice
+---
+
+# Session — <Phase id> : <Concise title>
+
+> **Status : QUEUED.** Drafted at the close of session `<NNN>` (commit `<short-sha>`). One-paragraph "why now" — what just shipped, what stays queued, what unblocks first.
+>
+> **Goal.** One sentence — what a fresh agent ships if they execute this prompt cleanly.
+>
+> **Why now.** One sentence — what changes if this slice doesn't ship next.
+
+**Project root.** `<absolute-path>`
+**Branch.** `main` (single branch, push at end).
+**Session log target.** `session-logs/YY-MM-DD-NNN-<slug>.md`.
+**Expected size.** `<1 h | 2-3 h | half-day>`. `<No | X>` schema change. `<No | X>` migration. `<No | X>` UI mount.
+
+---
+
+## CONTEXT — what changed since the parent prompt was drafted
+
+Three to six bullets, strict diff against the parent's assumptions, with commit refs.
+
+- **<What shipped>** (session NNN, commit `<sha>`). One-sentence summary + the constraint it imposes on this session.
+- **<Reusable surface>**. Where the analogue lives (file path) + what's safe to copy vs extend.
+- **<Standing convention>** this session must honor.
+
+---
+
+## REFERENCE FILES (read these before writing)
+
+Paths only, no excerpts.
+
+1. **`<closest analogue>`** — what shape to mirror.
+2. **`<schema block>`** — the table / module this session touches.
+3. **`<helper>`** — the signature that must not drift.
+4. **`<gate>`** — auth / hooks / middleware that wraps the new surface.
+
+---
+
+## SCOPE (must-have → should-have → defer)
+
+### MUST HAVE — ship these or don't push
+
+1. **`<file>`** — what it does, the verbs / fields / shape, the failure modes.
+2. **`<file>`** — same.
+3. **<Cross-cutting invariant>** — list explicitly so the audit checklist is ready.
+
+### SHOULD HAVE — same session if time permits
+
+4. **<extra surface / smoke target / helper extraction>** with a one-line rationale.
+
+### DEFER if time runs short
+
+- **<Sub-slice>** — lives in Section `<id>`. Reason.
+
+---
+
+## BUILD (in this order)
+
+1. Read the reference files end-to-end first.
+2. **`<file>`** — write in the order above. Smoke manually.
+3. **`<file>`** — same.
+4. **`pnpm check`** + **`pnpm build`** (or the equivalent) inline. Both green.
+
+---
+
+## VERIFY
+
+Concrete smoke checks — each one a verb + expected envelope.
+
+- **<Invariant 1>.** `<concrete test>` → `<expected envelope>`.
+- **<Invariant 2>.** Same shape.
+- **<No regression>.** List the surfaces this session must not break.
+- **`npx cockpit check`** 0 FAIL before push.
+
+---
+
+## DO NOT
+
+Anti-patterns + scope creep guards.
+
+- **Do not <anti-pattern>.** Reason.
+- **Do not <scope creep>.** Reason — lives in `<id>`.
+- **Do not skip <safety>.** Reason.
+
+---
+
+## AT END OF SESSION
+
+1. Tests / build / typecheck green.
+2. Migration applied (or N/A).
+3. `git add` only this session's files (no `-A`).
+4. Commit message :
+   ```
+   feat(<phase>): <one-line — what shipped>
+   ```
+5. **Post-implementation audit** (REQUIRED for : multi-tenancy on a new entity / schema / auth / billing / voice ; SKIP for pure UI / doc-only / trivial). Use `cockpit/templates/audit-brief.md`. Apply findings inline.
+6. Write **`session-logs/YY-MM-DD-NNN-<slug>.md`** : `npx cockpit new log --slug <slug>`, then fill.
+7. **Draft next session's prompt** : `npx cockpit new prompt --slug <next-slug>`, then fill.
+8. **`npx cockpit check`** — must exit 0 FAIL. Fix any drift inline.
+9. `git push`.
+
+---
+
+## EXPECTED OUTPUT
+
+- **New files :** `<path>` + the next-session prompt.
+- **Updated :** `<path>` + `cockpit/state.json` + `cockpit/now.md` + `cockpit/roadmap.md`.
+- **Commit count :** `<N>`.
+- **Migration count :** `<N>`.
+- **Session log :** one written.
+
+---
+
+*Self-contained. A fresh agent reads this prompt + the reference files + the closest analogue, ships every MUST first, the SHOULDs if time, defers the rest with explicit rationale, writes the log, drafts the next prompt, commits + pushes after `npx cockpit check` is green. No regression on prior phases.*