krow_backend/docs/handover.md

Handover

Written 2026-08-28, when the machine this was built on was retired.

Everything Claude Code "remembers" lives in ~/.claude/projects/<mangled-path>/ on one machine, keyed to the absolute path of the checkout. It does not sync, and a different path on a new machine reads a different folder. So the durable record is this file, in the repository, where git carries it and any path works.

Read CLAUDE.md first — it is the governing document. This file is what it does not say: what was decided, what is deployed, and which parts bite.

---

Where things stand

Deployed. Backend at https://mcp.krowforce.com, frontend at https://platform.krowforce.com, Kubernetes statefulset krow in namespace krow, pods named krow-1 and krow-2 (they start at 1, not 0).

ssh root@<host> -p 4422 "kubectl -n krow rollout restart statefulset/krow && \
  kubectl -n krow rollout status statefulset/krow --timeout=180s"

Verify a deployment — 55 checks including a real agent run:

KROW_EMAIL=... KROW_PASSWORD=... make verify-deploy BASE=https://mcp.krowforce.com

Auth runs BEFORE routing, so an unauthenticated probe answers 401 for every path including ones that do not exist. curl cannot tell a missing endpoint from a guarded one; only an authenticated check can.

Two runtime steps a deploy does not do, both easy to forget because the API looks healthy without them:

kubectl -n krow exec krow-1 -- importagents --org <slug>   # publishes agents/ and skills/
kubectl -n krow exec krow-1 -- ingest --org <slug>         # ingests knowledge/

Without the first, every Owliver question answers 404. Without the second, retrieval finds nothing. The org slug is krow-dev — a hardcoded constant (internal/orgctx.DevOrgSlug), not configuration.

The endpoint count is a signal. GET /api/v1/version reports it. Agent run routes are not registered without a model credential, so 56 means no ANTHROPIC_API_KEY and 58 means there is one. A keyless deployment boots cleanly under APP_ENV=staging and refuses under production.

---

Decisions taken, so they are not relitigated

§12, who authors agents: self-serve, split by visibility. personal agents are authored in the UI, POST to /api/v1/agent-definitions, and are runnable immediately; evals are not required for them. organization agents stay as files published by importagents on deploy — that deploy step is the approval workflow, and §9's eval requirement still applies. §12 warned self-serve needs "3× the platform"; it does not here, because I1 means an agent runs as its caller and cannot exceed their access, I4 means writes still need a human, and the spec format has no limits block so budgets cannot be raised by an author.

A rejected candidate counts as screened. It ranks with ai_screened: rejection overwrites the stage it came from, so shortlisted can never be claimed. An assigned candidate counts as hired, matching the backend's existing status IN ('hired','assigned').

Seeded profile scores are the formula's output, not hand-authored narrative. Recalculating a seeded profile is a no-op, and a skill-check enforces it.

---

Conventions the schema actively contradicts

These are the ones that produce confident, wrong numbers rather than an error.

job_applications.screened_at is vestigial. Nothing writes it. "Screened" means status <> 'applied', in about eight places in the frontend. Reading the column reported 1 screened of 24 where the truth was 14.

A score of 0 means "not rated", never "rated zero". Every score column is NOT NULL, so there is no null to distinguish it — that is the trap. Applies to ai_score, client_rating, krow_score, reliability_score, attendance_score, performance_score, experience_years. Aggregates need FILTER (WHERE col > 0) and a stated basis count. Counting zeros once reported "16 weak candidates averaging 28" for a pool that was 1 weak averaging 76.

Anchors to check against: applications are 9 scored averaging 76; workers are 5 rated of 9, client rating 4.70.

Genuine zeros, do not filter these: overtime_hours, minutes_late, xp, profile_completion, and actual_hours (0 only on absent/no_show shifts).

absent and no_show are both missed shifts, but only one is a no-show. attendance.js is canonical.

attendance_score defaults to 100 for display and must never be a scoring input. A profile with no evidence otherwise scores 12 and leaves the "not yet scored" band.

The stage ladder lives once, in krow-demo/src/lib/hiringRecords.js. It was three byte-identical private copies, all missing rejected and assigned, which indexOf scored -1 and dropped from every bucket including applied.

---

Things that will waste your afternoon

A space in the checkout path breaks path derivation. This repo lives under Krow Project /, and it has bitten three times: an unquoted $(CURDIR) in the Makefile, `file://${process.argv[1]}` in a script guard, and new URL(...).pathname in scripts/oracle.mjs (use fileURLToPath). Any new path derivation is guilty until tested there.

seed.json is generated from krow-demo/src/api/seed.js. Never edit it. npm run seed:fixture writes it, npm run seed:check verifies, and the skill-check compares byte-for-byte. ShiftRecord is excluded on purpose: the Go seeder generates it against now.

Shift data is anchored to today, so anything asserting against it is date-dependent unless the anchor is pinned. buildShiftsAt(anchor) exists for that. One detector had a Friday-and-Saturday blind spot for exactly this reason.

Database tests skip when PostgreSQL is unreachable (testutil calls t.Skipf). go test then exits 0 having run almost nothing. CI has a guard that fails on any skip other than TestLive*; keep it.

The eval suites use a scripted model. They prove the permission boundary, not answer quality. make eval-live uses the real model and costs tokens; it has never been run.

---

Still outstanding

• The knowledge corpus is 8 documents locally; production still has the 2 seeded ones until ingest runs there.
• ANTHROPIC_API_KEY was pasted into a chat transcript and is live in a Kubernetes Secret. Rotate it.
• Deployments report version=dev: the image is built without --build-arg VERSION. make docker-build passes it.
• APP_ENV=staging on the deployment, so the production config guards are off.
• Skills are still stored in user_preferences; agents were moved to the registry and skills were deliberately left for their own pass.
• definition_versions is empty — immutable versioning is built, trigger-proven, and nothing has gone through it because importagents republishes in place.
• CI tests but does not deploy. The README's claim that migrations are "run by CI against the target database" is still aspirational.
• The fixture-drift CI jobs need FRONTEND_REPO_TOKEN to see the sibling repo, and fail rather than pass quietly without it.
• The remote is Gitea. These are GitHub Actions workflows; they do nothing until a compatible runner exists.

---

Setting up a new machine

git clone <backend> krow-backend && git clone <frontend> krow-demo
cp krow-backend/CLAUDE.md ./claude.md      # the governing doc lives above both repos

Needs: Go (see go-api/go.mod), Node 20, PostgreSQL, Docker, and Ollama with nomic-embed-text if you want semantic retrieval locally. Then:

cd krow-backend && cp .env.example .env    # fill it in; .env is gitignored
make migrate-up && make seed
make import-agents ORG=krow-dev
make ingest ORG=krow-dev
go run ./go-api/cmd/setpassword -email demo@krow.app

cd ../krow-demo && npm ci && cp .env.example .env
# VITE_AGENT_API=/api/v1 for local dev (vite proxies it);
# production passes an absolute URL as a Docker build arg instead.

.env files are not in git and must be carried across by hand.