microdao-daarion/docs/backlog/backlog.md

Engineering Backlog Bridge — DAARION.city

Overview

The Engineering Backlog Bridge converts Risk/Pressure digest signals into a managed, structured backlog of engineering work items. It closes the loop:

observe (Risk/Pressure) → decide (digest) → plan (backlog) → enforce (gates)

No LLM. Fully deterministic. Policy-driven. Idempotent (weekly dedupe).

---

Data Model

BacklogItem

Field	Type	Description
id	string	bl_<hex12>
created_at	ISO ts	When created
updated_at	ISO ts	Last modification
env	string	prod / staging / dev
service	string	DAARION service name
category	enum	arch_review, refactor, slo_hardening, cleanup_followups, security
title	string	Short human-readable label
description	string	Bullet-list of signals + context
priority	enum	P0 .. P3
status	enum	See Workflow below
owner	string	oncall / cto / team name
due_date	YYYY-MM-DD	Computed from category due_days
source	string	risk / pressure / digest / manual
dedupe_key	string	platform_backlog:{YYYY-WW}:{env}:{service}:{category}
evidence_refs	dict	alerts[], incidents[], release_checks[], artifacts[], followups[]
tags	list	["auto", "week:2026-W08", "rule:arch_review_required"]
meta	dict	Free-form metadata

BacklogEvent (timeline)

Field	Type	Description
id	string	ev_<hex12>
item_id	string	FK to BacklogItem
ts	ISO ts	Event timestamp
type	enum	created, status_change, comment, auto_update
message	string	Human-readable description
actor	string	Who triggered the event
meta	dict	Old/new status, rule name, etc.

---

Workflow

open ──► in_progress ──► done
  │            │
  │            ▼
  └──► blocked ──► in_progress
  │
  └──► canceled (terminal)

From	Allowed targets
open	in_progress, blocked, canceled
in_progress	blocked, done, canceled
blocked	open, in_progress, canceled
done	(none — terminal)
canceled	(none — terminal)

Transitions are enforced by validate_transition() in backlog_store.py.

---

Auto-generation Rules

Rules are evaluated per-service from config/backlog_policy.yml. All conditions in when must hold (AND logic). First matching rule per category wins (no duplicate categories per service per week).

Rule name	Trigger condition	Category	Priority
arch_review_required	pressure_requires_arch_review: true	arch_review	P1 / 14d
high_pressure_refactor	pressure_band AND risk_band ∈ high/critical	refactor	P1 / 21d
slo_violations	risk_has_slo_violations: true	slo_hardening	P2 / 30d
followup_backlog	followups_overdue > 0	cleanup_followups	P2 / 14d

---

Dedupe Logic

Each item has a dedupe_key:

platform_backlog:{YYYY-WW}:{env}:{service}:{category}

upsert() uses this key:

• First run of week → creates the item.
• Subsequent runs → updates title/description/evidence_refs (preserves status/owner).

This means weekly re-generation is safe and idempotent.

---

API

HTTP Endpoints

Method	Path	RBAC	Description
GET	/v1/backlog/dashboard?env=prod	tools.backlog.read	Status/priority/overdue summary
GET	/v1/backlog/items	tools.backlog.read	Filtered item list
GET	/v1/backlog/items/{id}	tools.backlog.read	Single item + event timeline
POST	/v1/backlog/generate/weekly	tools.backlog.admin	Trigger weekly auto-generation

Query params for /v1/backlog/items: env, service, status, owner, category, due_before, limit, offset

Tool: backlog_tool

{
  "action": "list|get|dashboard|create|upsert|set_status|add_comment|close|auto_generate_weekly|cleanup",
  "env": "prod",
  "id": "bl_abc...",
  "service": "gateway",
  "status": "open",
  "item": { ... },
  "message": "...",
  "actor": "cto"
}

RBAC

Entitlement	Roles	Actions
tools.backlog.read	cto, oncall, interface	list, get, dashboard
tools.backlog.write	cto, oncall	create, upsert, set_status, add_comment, close
tools.backlog.admin	cto only	auto_generate_weekly, cleanup

---

Storage Backends

Backend	Env var	Notes
auto	BACKLOG_BACKEND=auto	Postgres → JSONL fallback (default)
postgres	BACKLOG_BACKEND=postgres	Primary (requires migration)
jsonl	BACKLOG_BACKEND=jsonl	Filesystem append-only (MVP)
memory	BACKLOG_BACKEND=memory	Tests only
null	BACKLOG_BACKEND=null	No-op

Files (JSONL): ops/backlog/items.jsonl, ops/backlog/events.jsonl

Postgres: run ops/scripts/migrate_backlog_postgres.py first.

---

Scheduled Jobs

Job	Schedule	Description
weekly_backlog_generate	Mon 06:20 UTC	Generate items from latest platform digest
daily_backlog_cleanup	Daily 03:40 UTC	Remove done/canceled items older than retention_days

---

Examples

Manual create via tool

{
  "action": "create",
  "env": "prod",
  "item": {
    "service": "gateway",
    "category": "security",
    "title": "[SEC] Patch CVE-2026-xxxx in gateway",
    "priority": "P0",
    "due_date": "2026-03-01",
    "owner": "cto",
    "source": "manual",
    "dedupe_key": "manual:2026-W08:prod:gateway:security"
  }
}

Close an item

{
  "action": "close",
  "id": "bl_abc123456789",
  "status": "done",
  "message": "Architecture review completed — no rework needed."
}

Run weekly auto-generation

# HTTP
POST /v1/backlog/generate/weekly?env=prod

# Tool
{ "action": "auto_generate_weekly", "env": "prod" }