project-octopus

A centralized project status service. Anyone in the org can look up any project's current status without asking its owner. Status is derived entirely from systems of record — Linear, GitHub, Slack, and meeting notes — and turned into a scored, evidence-linked view; no human writes a status update. Phase 1 is the spine: registry loader, structured logger, Postgres schema, project upserts, sync-run lifecycle, Slack alerter, hourly sync CLI, dead-man's switch, and a /status page. Narrative extraction and scoring land in Phase 2.

Prerequisites

• Node 22
• pnpm 11, via corepack (corepack pnpm ..., never bare pnpm, so the pinned version in package.json is always the one that runs)
• Docker, for Postgres-backed tests (testcontainers)

Setup

corepack pnpm install
cp .env.example .env   # fill in DATABASE_URL at minimum
corepack pnpm migrate

Commands

Command	Purpose
corepack pnpm dev	Run the /status app locally
corepack pnpm build	Production build (also a CI gate — it resolves module specifiers more strictly than typecheck or tests)
corepack pnpm test	Run the full test suite
corepack pnpm typecheck	tsc --noEmit
corepack pnpm migrate	Apply Postgres migrations (drizzle-kit migrate)
corepack pnpm sync	Run one sync: validate the registry, upsert projects, close out a sync_run
corepack pnpm watchdog	Dead-man's switch: alert if no sync has succeeded recently
corepack pnpm report	Write the test/coverage summary artifact used in CI

Testing against Postgres

Tests that touch the database spin up a real Postgres via testcontainers. If Docker is provided by colima rather than Docker Desktop, set these two env vars in the shell that runs the tests (not needed on GitHub Actions runners, where Docker is native):

DOCKER_HOST=unix:///path/to/.colima/default/docker.sock \
TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock \
corepack pnpm vitest run

CI and scheduled workflows

ci.yml runs typecheck, the test suite, and the build on every push and PR. sync.yml and watchdog.yml exist but their schedule: triggers are disabled in Phase 1 — the DATABASE_URL and SLACK_ALERT_WEBHOOK_URL secrets don't exist yet, and projects.yaml carries a placeholder Linear project ID. Both workflows remain runnable via workflow_dispatch; the schedules come back in Phase 2.

Further reading

• Spec: docs/superpowers/specs/2026-08-20-project-octopus-design.md
• Phase 1 plan: docs/superpowers/plans/2026-08-20-octopus-phase-1-skeleton.md