bec3e2f6a9
Now that BB1's port 5432 is freed, CI gets past the port-bind step and actually attempts to run the tests. The next failure is: psycopg.OperationalError: connection to server at "127.0.0.1", port 5432 failed: Connection refused The job tried 127.0.0.1:5432 but the postgres service container had just been brought up and wasn't accepting connections yet. The '5432:5432' port mapping for self-hosted act_runner is racy — the host-side bind sometimes lags the service ready signal, and the job's 'Apply schema' step runs before pg_isready returns 0. Fix: - Use the service name 'postgres' as DAMASCUS_PG_HOST. In act_runner's service network, the service name is the DNS hostname, no port mapping required. - Drop the now-unused 'ports: 5432:5432' binding. This is the same fix the cron branch fix/compose-db-volume-self-heal should land in (PR #7). It's small enough to be a follow-up to this PR; if the test workflow on BB1's runner doesn't resolve 'postgres', we can revisit. Co-Authored-By: Claude <noreply@anthropic.com>
Damascus Orchestrator
A self-hosted work-item state machine that autonomously advances stories through spec → build → review → merge. Designed per multi-project-orchestration-plan_1.md (the design doc this repo implements).
Quick start
# Start the stack (Postgres + Redis + Taskiq worker + scheduler)
docker compose up -d --build
# Apply schema (creates the DB + all tables/types/triggers)
docker compose exec orchestrator damascus init
# Manual one-shot cycle (operators / E2E). The Taskiq worker is the
# automatic trigger — you do not normally need to run this by hand.
docker compose exec orchestrator damascus cycle
# External concurrency view
docker compose exec orchestrator damascus status
# Run the contract + unit suite (needs a Postgres on 127.0.0.1:5432)
pip install -e . pytest psycopg[binary]
pytest tests/contract/ tests/unit/ -v
# Run the E2E suite (needs the docker-compose stack up)
pip install pytest psycopg
pytest tests/ -v
What this repo contains
src/damascus/— the Python package (cycle, phases, state, git_ops, llm, cli, relay, wiki, tasks, config)tests/— the suite (contract + unit + E2E; the executable form of the design doc)schema.sql— Postgres 16 schema (work_items, coordination_gates, human_issues, cost_ledger, events_outbox)docker-compose.yml— the stack (db + redis + orchestrator worker + scheduler + sidecar-status)Dockerfile— the orchestrator image (Python 3.12 + git + claude-code + BMAD + LLM-wiki + ollama binary).gitea/workflows/— CIskills/SKILL.md— operator-facing skill
What this repo does NOT contain
- The wiki (
kaykayyali/damascus-wiki) — separate repo with the contract docs - The test project repos (
wh40k-pc,restitution) — separate repos with their own BMAD stories - The lore entry about this project (
kaykayyali/lore→Infrastructure/Damascus-Orchestrator)
Architecture (one paragraph)
Postgres is the source of truth on work-item state (design §3). Each story row
flows through three loops: spec-refiner (LLM via LiteLLM writes an implementable
spec), code-builder (Claude Code via LiteLLM writes the code in a git worktree,
opens a real Gitea PR), reviewer (re-runs the spec's test command, gates on
objective pass/fail, merges via Gitea API on pass). Atomic claim uses
SELECT ... FOR UPDATE SKIP LOCKED. Taskiq (a BullMQ-equivalent Python queue,
§13) with a Redis broker is the recurring trigger; the worker's --concurrency N
is the global concurrency cap (§10). Every phase transition emits a typed
verdict and an events_outbox row in the same transaction. An attempt budget
guarantees termination — a non-pass verdict that exhausts the budget parks the
item as blocked and opens a human_issue (§5/§16). The human is async — open
questions become human_issues rows, never synchronous blocks.
Full design + contracts in the wiki: kaykayyali/damascus-wiki.
Cross-references
- Design doc:
kaykayyali/damascus-wiki/raw/articles/multi-project-orchestration-plan-1.md - Contracts:
kaykayyali/damascus-wiki/concepts/spec-refiner-contract.md,builder-contract.md,reviewer-contract.md,state-resume-protocol.md - Lore entry:
kaykayyali/lore→Infrastructure/Damascus-Orchestrator - Test session:
kaykayyali/damascus-wiki/queries/damascus-orchestrator/2026-06-23-test-session.md - Spec-refiner gap:
kaykayyali/damascus-wiki/queries/damascus-orchestrator/spec-refiner-gap-2026-06-23.md
License
Internal.