Validation: feat: Makefile, docker-compose improvements, and doc updates

validation-80-2026-07-17 Doc

validation pass

Project

Verdict: PASS

Ticket

ldraney/intelligentstaffingsystems#80 (PR #81) — Added Makefile (dev entry point), expanded idempotent seed data (Leads, CatalogEntries, Messages), and updated docs (local-dev-setup.md, architecture.md, pipeline.md, README.md).

Board item: #1871 on board-iss. Merge commit: e11e04a.

Environment

Production k3s cluster, namespace intelligentstaffingsystems. Public URL: https://intelligentstaffingsystems.ai. ArgoCD application: intelligentstaffingsystems.

Changes are developer-facing only (Makefile, seed data, docs) — zero production runtime impact. Validation covers code correctness on main plus production health (no regression).

Checks

#	Criterion	How Verified	Result	Evidence
1	Makefile exists with all expected targets (help, dev, down, logs, setup, migrate, seed, console, test, lint, security, ci)	Read Makefile on main	PASS	66-line Makefile present with all 12 targets. <code>.DEFAULT_GOAL := help</code>. Uses <code>docker compose run --rm web</code> pattern.
2	db/seeds.rb is idempotent and creates representative data	Read db/seeds.rb on main	PASS	Seeds 4 Leads (admin, client, 2 leads), 3 CatalogEntries (one per pillar), and sample Message threads. Uses <code>find_or_create_by!</code> throughout for idempotency.
3	docs/local-dev-setup.md documents Makefile usage	Read docs/local-dev-setup.md on main	PASS	Full Makefile target table, prerequisites section, first-time setup, running instructions, raw docker compose equivalents. References Makefile as "single entry point."
4	README.md updated with Makefile references	Read README.md on main	PASS	Local development section references <code>make setup</code>, <code>make dev</code>, <code>make logs</code>, <code>make ci</code>.
5	docs/architecture.md and docs/pipeline.md updated	Read both docs on main	PASS	Architecture shows ISS namespace topology. Pipeline shows local dev with docker-compose on :9999.
6	Production app is healthy (no regression from merge)	kubectl get pods + curl	PASS	Pod <code>intelligentstaffingsystems-6d6896dd95-ls9k4</code>: 1/1 Running, 0 restarts. Root URL returns HTTP 200. Title: "Intelligence Staffing Systems — Enterprise infrastructure for small businesses".
7	Woodpecker pipeline green for merge commit	Woodpecker list_pipelines	N/A	No push pipeline triggered for merge commit <code>e11e04a</code> (known gap: Forgejo squash merges don't trigger Woodpecker push events). Changes are developer-facing only — no new image build required.

Regression Check

Production site verified healthy:

GET / — HTTP 200, correct page title and CSS assets loading
GET /catalog — HTTP 302 (auth redirect, expected)
Deployment: 1/1 READY, 1 available
ArgoCD sync status: Synced (health: Degraded due to unrelated crash-looping pod)

No regression from this PR. Changes are Makefile, seeds, and docs — they do not alter application runtime behavior.

Discovered Issues

These are pre-existing issues, not introduced by PR #81:

Crash-looping pod: intelligentstaffingsystems-8474c67bc8-nxphp in Init:CrashLoopBackOff. Init container (migrate) fails with PLACEHOLDER_POSTGRES_HOST — deployment config has a placeholder database hostname instead of a real one. Causes ArgoCD to report Degraded.
CI pipeline failures: All recent Woodpecker pipelines show failure. Pipeline #90 (most recent, commit ca24329) fails in the test step with a require error. This is a pre-existing CI issue.
Push event gap: Forgejo squash merges not triggering Woodpecker push events (known issue per project memory).