[zwanski-start]

Closes #56

What changed

Backlog state (not committed / not ready)

• Feature gains backlog (bool), maturity (alpha | limited_beta | beta, nullable) and spec_notes columns. Existing features.db files are migrated automatically, and existing features default to non-backlog and untagged.
• Guardrail: agents only start work from Pending, never from Backlog:
  • MCP feature_mark_in_progress / feature_claim_and_get refuse backlog features, and the atomic claim SQL checks backlog = 0.
  • The orchestrator's get_ready_features, get_resumable_features and batch chain extension skip backlog features (and needs-input ones in chain extension).
  • get_all_complete doesn't wait on backlog items, so the orchestrator exits normally and prints how many backlog features were left unbuilt.
• New endpoints:
  • GET /api/projects/{p}/features/{id}/readiness: runs the spec-completeness checklist.
  • POST /api/projects/{p}/features/{id}/promote {force?: bool}: Backlog → Pending. It returns 409 with the failing checks unless force: true (explicit human override).
  • POST /api/projects/{p}/features/{id}/backlog: Pending → Backlog. Refused for done or in-progress features.
• GET /features returns a new backlog list. Graph nodes can have status backlog and carry maturity.

Iterative spec roadmapping (maturity tags)

• PATCH /features/{id} accepts maturity and spec_notes; an explicit null clears them. POST /features and /features/bulk accept backlog, maturity and spec_notes.
• Prioritization: the build queue is sorted by maturity rank first, then the existing dependency-aware scheduling score, then priority. This applies in the orchestrator, MCP feature_get_ready and dependency_resolver.get_ready_features.
• The ordering is configurable through a new global setting maturity_priority (GET/PATCH /api/settings, default beta > limited_beta > alpha). The orchestrator re-reads it every loop, so a change applies without restarting the agent.
• Ready checks (api/maturity.py): description filled in, at least one acceptance/test step, maturity tag assigned, all dependencies exist, and no dependency still in Backlog.

UI

• A Backlog column with dashed cards. It only appears once something is in the backlog, so boards that don't use the feature are unchanged.
• A maturity badge on cards and in the feature modal.
• Maturity filter chips (All / Beta / Limited beta / Alpha / Untagged) with counts. Hovering a chip shows the per-stage breakdown, and a "Pending: N beta · M alpha" summary covers the dashboard nice-to-have.
• A Spec Review panel in the feature modal with:
  • maturity selector and notes
  • live ready checklist
  • Promote to Pending, disabled until the checks pass, plus a two-step Override checks… for the human override
  • Move to Backlog
• The Add Feature form can set a maturity tag and has an "Add to Backlog" checkbox.
• Settings → Agent Configuration has a Maturity Priority list you reorder with up/down buttons.
• The dependency graph styles backlog nodes in grey/dashed.

How I verified it

• ruff check . passes. pytest test_backlog_maturity.py test_dependency_resolver.py test_client.py gives 54 passed. python test_security.py passes.
• New test_backlog_maturity.py (21 tests) covers:
  • order parsing and sorting
  • backlog exclusion in the resolver and the orchestrator
  • orchestrator completion when only backlog items remain
  • the readiness checklist
  • migration of a legacy DB
  • router list/promote (409 and force)/backlog/maturity update/readiness
• npm run lint shows no new warnings. npm run build succeeds.
• Manual check: I ran the backend and the Vite dev server (port 5247) against a seeded demo project in an isolated HOME. In Playwright I checked:
  • the board shows the Backlog column, badges and filter
  • the filter works
  • the modal shows the failing ready checks with Promote disabled
  • override promotion moves the card to Pending, and the modal updates live
  • Move to Backlog works
  • reordering in Settings persists (['beta','alpha','limited_beta'])

Assumptions / design decisions

• Board semantics: I didn't add a separate "Review / QA" column. In AutoForge a feature goes from in-progress straight to passing once the agent verifies it, and there is no PR step per feature. The existing Needs Input / In Progress / Done columns cover the rest.
• Ready checks are enforced on promotion out of Backlog (409 unless forced). Creating a feature directly as Pending (initializer, expand, MCP feature_create, Add Feature without the backlog box) does not run the checks. This keeps existing flows working and avoids requiring maturity tags on every generated feature.
• Untagged features rank after all tagged ones. Projects that tag nothing keep exactly the old ordering.
• Progress totals (x / total) still include backlog features. Only scheduling and completion ignore them.
• The backlog flag can't be changed through PATCH. It only moves through /promote (checked) and /backlog, so the checks can't be bypassed by accident.

🤖 Generated with Claude Code

[zwanski-start]

🔍 QA report: ✅ Passed

Tester: Ken (cubefarm agent, in a fresh session) · Round: 1 · Author: Dennis

Backlog state, maturity tags, ready checks and configurable maturity priority work end to end: API, MCP/orchestrator guardrails, migration of a legacy features.db, and UI (Backlog column, badges, filter, Spec Review panel with gated and override promotion, Settings reorder, graph styling). ruff is clean; mypy and pytest results match master exactly, so all failures are in unrelated files; the 21 new tests pass; the UI build and lint pass with no new warnings. The only issue found is cosmetic: the dependency graph legend has no Backlog entry.

	Check	Details
✅	Legacy DB migration	Created features.db with master's schema (no backlog columns), registered it, and let the PR server open it. backlog BOOLEAN NOT NULL DEFAULT 0, maturity and spec_notes were added, and existing features came back as backlog=false, maturity=null.
✅	Tag alpha/limited_beta/beta via API	PATCH sets maturity; an explicit null clears it; spec_notes are trimmed; an invalid tag ('gamma') returns 422. PATCH {backlog:false} is ignored, so ready checks can't be bypassed.
✅	Ready checks enforced on promotion	GET /readiness lists the 5 checks. POST /promote returns 409 with the failing checks; force:true promotes. Promoting a non-backlog feature returns 400; unknown feature or project returns 404; invalid JSON returns 422. A dependency still in Backlog fails the 'dependencies_committed' check.
✅	Move to backlog	POST /backlog works for a pending feature, returns 400 for a done feature and 404 for an unknown one. The in-progress guard is present in the code.
✅	Backlog excluded from agent queue	Against a real DB: ParallelOrchestrator.get_ready_features and MCP feature_get_ready leave out backlog features. feature_claim_and_get(6) and feature_mark_in_progress(7) return 'in the backlog (not ready to build)'. feature_get_stats reports the backlog count.
✅	Maturity-ordered, configurable queue	With maturity_priority set to [alpha, beta, limited_beta], both the orchestrator and MCP ready lists came back as [#1 alpha, #5 beta, #4 untagged]. PATCH /api/settings rejects partial, duplicate or unknown lists with 422.
✅	UI: Backlog column, maturity badges, filter	The Backlog column shows dashed cards. Maturity badges appear on cards and in the modal. The Alpha filter chip correctly narrowed every column, and the 'Pending: N beta · …' summary is shown.
✅	UI: Spec Review panel	Promote to Pending is disabled while the maturity check fails. Picking Beta updates the checklist live; Promote saves the tag first and then promotes (confirmed via the API). The two-step 'Override checks…' / 'Yes, promote anyway' promoted #7 even though its dependency was in Backlog. Move to Backlog works live.
✅	UI: Add Feature with backlog and maturity	Created a feature with a Unicode name, Limited beta and Add to Backlog checked. The API showed backlog=true, maturity=limited_beta, and the card appeared in the Backlog column.
✅	UI: Settings maturity priority	'Move Alpha up' persisted as ['beta','alpha','limited_beta'] (checked via GET /api/settings).
✅	UI: Dependency graph	The backlog node is grey and dashed with an archive icon. Minor: the legend has no Backlog entry.
✅	Responsive / dark mode / console	At 390x844 with the sidebar collapsed there is no horizontal scroll (scrollWidth=390) and chips and cards wrap. Dark mode renders correctly. Console: 0 errors; the only warnings are Radix DialogContent aria-describedby warnings from dialogs that already exist on master.
✅	WebSocket /ws/projects/{name}	Connected and received agent_status, dev_server_status and progress messages.
⏭️	Playwright e2e suite	All 15 specs skipped themselves in this environment (they need an existing project or Claude setup). I ran them with a throwaway config pointing at /usr/bin/chromium because the browser download timed out.
✅	Security / cleanup	security.py and the localhost middleware are untouched. No secrets in the server log. Server stopped, ports 5345 and 5173 free, worktree clean.

🧪 Commands run

Command	Result
ruff check .	All checks passed
mypy .	24 errors, the same 24 as origin/master (none in changed files)
python -m pytest -q	165 passed, 21 failed; the 21 failures are the same set as on origin/master (e.g. test_devserver_security)
python -m pytest -q test_backlog_maturity.py	21 passed
python test_security.py && python test_security_integration.py	ALL TESTS PASSED
npm --prefix ui run lint	0 errors, 6 warnings (same as master)
npm --prefix ui run build	tsc -b + vite build succeeded
uvicorn server.main:app --port 5345 (isolated HOME, no API key) + curl probes of features/readiness/promote/backlog/settings/graph	Expected status codes (200/400/404/409/422)
Python probe of ParallelOrchestrator.get_ready_features / get_all_complete and MCP feature_get_ready / claim / mark_in_progress / stats	Backlog excluded or refused; maturity order applied
npx playwright test (VITE_API_PORT=5345, system chromium)	15 skipped

No browser screenshots were taken in this round.

_{Posted by cubefarm · merges automatically once GitHub's checks pass}