close the comms channel, keep what was still open
The sidecar-app-store channel ran one night, from per-user Linux accounts to a member's first agent turn, and is deleted now the work has landed. A spent channel left in place gets read as current, which is worse than none. Three things lived only in those docs and move to TODO.md rather than disappearing: deprovisionOsAccount (observed on production — a deleted member kept a shell, a running container and 454M of data, with their uid free to reissue), the terminal replaying query sequences as keystrokes, and agent sessions not being durable, which is one missing property behind three symptoms. The deprovision spec itself already lives in docs/. CLAUDE.md's section is rewritten from "here is the current channel" to how to run one, since the answer to "which channels exist" is now none. What is worth keeping is the protocol that emerged: numbered alternating files, parity as the author, a reply even when there is nothing to say, and termination on a checkable condition rather than on someone deciding it feels finished. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -126,7 +126,7 @@ history was deleted because it had drifted from the real schema. Treat the schem
|
||||
files, as the source of truth.
|
||||
|
||||
**Declare multi-column uniqueness as `uniqueIndex('uq_…').on(a, b)`, never `unique('uq_…').on(a, b)`** —
|
||||
drizzle-kit mis-diffs named composite unique *constraints* and re-creates them on every push, which used
|
||||
drizzle-kit mis-diffs named composite unique _constraints_ and re-creates them on every push, which used
|
||||
to stop `db:push` on an unanswerable truncate prompt. Same for any foreign key whose generated name would
|
||||
exceed Postgres's 63-character identifier limit: name it explicitly. See `src/databases/CLAUDE.md` →
|
||||
"Composite keys" before adding either.
|
||||
@@ -170,7 +170,7 @@ ahead of everything, and it re-verifies the token itself so it covers routes tha
|
||||
survive the next door; refusing to boot does.
|
||||
|
||||
So **adding a router means adding one line to `CAPABILITIES`**. If the surface genuinely is not
|
||||
user-gated, add it to `EXEMPT_API_PREFIXES` in `totality.ts` *with a reason* — an unexplained exemption
|
||||
user-gated, add it to `EXEMPT_API_PREFIXES` in `totality.ts` _with a reason_ — an unexplained exemption
|
||||
is how the hole happened the first time.
|
||||
|
||||
The frontend hook `useCapabilities` **fails open** on purpose: hiding a dock icon is a courtesy, the
|
||||
@@ -219,12 +219,11 @@ so it rewrites every uncommitted file — including work in progress that isn't
|
||||
up as unexplained whitespace churn in someone else's diff. Run `bunx prettier --write <paths>` on the
|
||||
files you actually touched. `bun format` is only safe when the tree is otherwise clean.
|
||||
|
||||
|
||||
## Code Style
|
||||
|
||||
- **Paradigm**: functional — pure functions, immutability, composition
|
||||
- **TypeScript**: strict, no `any`. Type-only imports are required (`verbatimModuleSyntax`).
|
||||
- **Comments**: minimal, and about *why*. Don't narrate what the code already says.
|
||||
- **Comments**: minimal, and about _why_. Don't narrate what the code already says.
|
||||
- **Async**: always async/await
|
||||
- **Exports**: named only, no defaults
|
||||
- **Files**: `PascalCase.tsx` for components, `kebab-case.ts` for everything else
|
||||
@@ -323,7 +322,7 @@ link-focusable). Half the app still does this; none of the new code should.
|
||||
`f35c145`); **react-router's `<NavLink>`** for nav chrome, so active state comes from the router.
|
||||
The hand-rolled `isActive` in `Dock`/`Header` is scheduled for replacement (audit Phase 4) — don't
|
||||
copy it. A disabled entry renders as a `<span>`; a disabled `<a>` is not a thing. A control that
|
||||
*mutates* rather than navigates stays a `<button>`.
|
||||
_mutates_ rather than navigates stays a `<button>`.
|
||||
- **Route pairs.** A bare screen route plus a param route rendering the same component: `/chat` +
|
||||
`/chat/:sessionId`, `/jobs` + `/jobs/:id`, `/email` + `/email/:emailId`, `/headscale` +
|
||||
`/headscale/:section`. One `<Navigate … replace />` guard in the screen, placed after all hooks,
|
||||
@@ -339,23 +338,34 @@ link-focusable). Half the app still does this; none of the new code should.
|
||||
re-exported from `src/workspaces/officerdev/src/index.ts` (named exports only — the barrel
|
||||
deliberately avoids `export *` for app modules to keep `appRegistryMetas` from colliding).
|
||||
|
||||
## Before you start: check COMMS
|
||||
## COMMS — a channel between agents, when one is open
|
||||
|
||||
`COMMS/<work-stream>/` is a **tracked** channel between the agents working on this repo — several run on
|
||||
different machines, and findings used to reach each other by the owner relaying them from memory at the end of
|
||||
long sessions.
|
||||
`COMMS/<work-stream>/` is a **tracked** channel between agents working on this repo from different machines.
|
||||
It exists because findings used to reach each other by the owner relaying them from memory at the end of long
|
||||
sessions.
|
||||
|
||||
**If your task touches a work stream with a directory there, read its files first.** They carry what is
|
||||
verified, what is merely assumed, what is known broken, and what is waiting on a decision. Newest date wins;
|
||||
each directory's `README.md` states the convention.
|
||||
**There is no open channel right now.** `COMMS/sidecar-app-store/` ran for one night — per-user Linux
|
||||
accounts through to a member's first agent turn — and was deleted when the work landed, which is the
|
||||
convention rather than an oversight: a spent channel left in place gets read as current.
|
||||
|
||||
Current channels:
|
||||
If you open one:
|
||||
|
||||
- `COMMS/sidecar-app-store/` — the app store, per-user Linux accounts, per-user Docker, and the per-user
|
||||
Claude work that follows from them. Paired with `docs/per-user-linux-accounts.md`, which holds the durable
|
||||
reasoning; the handoffs hold the coordination.
|
||||
- **Read it before starting**, if your task touches its work stream. It carries what is verified, what is
|
||||
assumed, what is broken, and what is waiting on a decision — the parts a commit message does not hold.
|
||||
- **Number the files and alternate**, one per turn, odd for one agent and even for the other. The parity is
|
||||
the author; the alternation is the protocol. A push with no doc is then visibly a break rather than
|
||||
something to find by diffing, and "nothing to report" is still a turn worth taking — silence and a crashed
|
||||
agent read identically.
|
||||
- **End on a checkable condition**, not on either party's judgement: no open item is actionable by a
|
||||
participant. "I think we're done" can close a thread with work still in it.
|
||||
- **Durable reasoning goes in `docs/` or next to the code.** The channel is for coordination. When the work
|
||||
lands, delete the channel and move anything still open to `TODO.md`.
|
||||
|
||||
Write there instead of asking the owner to pass something along, and delete a handoff once it is spent.
|
||||
Two things that made it work, and neither is about either agent being more careful. One writes, the other
|
||||
verifies, and only the verifier runs things on a real machine — most of what was caught was invisible to
|
||||
reading and needed a live filesystem. And the author of a comment is the worst-placed person to notice the
|
||||
code disagrees with it: the two most serious defects were both found by whoever had not written the sentence
|
||||
explaining why it was safe.
|
||||
|
||||
## Further Reading
|
||||
|
||||
@@ -363,7 +373,7 @@ Write there instead of asking the owner to pass something along, and delete a ha
|
||||
a severity-ranked findings table, the channel-selection map and the four-phase plan
|
||||
- `docs/agent-coordination.md` — **the north star** for the workspace/panel work: agents on one
|
||||
dashboard coordinating with each other instead of through the human, the handoff protocol, and what
|
||||
is deliberately *not* being built. Read it before ranking, deferring or starting any panel item —
|
||||
is deliberately _not_ being built. Read it before ranking, deferring or starting any panel item —
|
||||
it is what `docs/workspace-panel-todo.md` is ranked against.
|
||||
- `docs/workspace-panels.md` — how the Workspace/Panel framework works: the layout tree, how a panel is
|
||||
mounted and what it knows, the URL-vs-channel split for panel-to-panel communication, and the
|
||||
|
||||
Reference in New Issue
Block a user