Skip to content

docs/devx: Features ledger + progress automation + drift report #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs/devx: Features ledger + progress automation + drift report #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ff6c686
docs: add grouped Features ledger with full columns, script-driven pr…
flyingrobots Sep 15, 2025
bc6b7dd
devx: add pre-commit hook to update weighted progress bars; document …
flyingrobots Sep 15, 2025
a9933b9
ci: add GitHub Action to auto-update progress on main merges; documen…
flyingrobots Sep 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .githooks/pre-commit
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
#!/usr/bin/env bash
set -euo pipefail

repo_root="$(git rev-parse --show-toplevel)"
cd "$repo_root"

if [ -f scripts/update_progress.py ]; then
echo "[pre-commit] Recomputing weighted progress and updating bars…"
if ! python3 scripts/update_progress.py; then
echo "[pre-commit] Progress update failed. Aborting commit." >&2
exit 1
fi
# Stage updated docs so the commit includes refreshed bars/KLoC
git add docs/features-ledger.md README.md || true
fi
Comment on lines +7 to +15
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

⚠️ Potential issue

This hook silently assumes python3 and force-stages files. Be smarter.

  • Bail out cleanly if python3 is missing.
  • Only stage docs if they actually changed.
 if [ -f scripts/update_progress.py ]; then
   echo "[pre-commit] Recomputing weighted progress and updating bars…"
-  if ! python3 scripts/update_progress.py; then
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "[pre-commit] python3 not found; skipping progress update." >&2
+  elif ! python3 scripts/update_progress.py; then
     echo "[pre-commit] Progress update failed. Aborting commit." >&2
     exit 1
   fi
-  # Stage updated docs so the commit includes refreshed bars/KLoC
-  git add docs/features-ledger.md README.md || true
+  # Stage updated docs only if changed
+  if ! git diff --quiet -- docs/features-ledger.md README.md; then
+    git add docs/features-ledger.md README.md || true
+  fi
 fi
🤖 Prompt for AI Agents 
.githooks/pre-commit around lines 7-15: the hook currently assumes python3
exists and always stages docs even if unchanged; update it so it first checks
for python3 (exit the hook gracefully with an informational message and do not
abort the commit if python3 is missing), then run scripts/update_progress.py and
only if it succeeds check whether docs/features-ledger.md or README.md were
actually modified before running git add (e.g. inspect git status or use git
diff to detect changes) so you do not force-stage files unnecessarily.


exit 0

47 changes: 47 additions & 0 deletions .github/workflows/update-progress.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: Update Progress Bars

on:
push:
branches: [ main ]
workflow_dispatch: {}
Comment on lines +3 to +6
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Lint your YAML and stop sprinkling spaces like confetti.

Fix bracket spacing and truthy lint noise.

 on:
   push:
-    branches: [ main ]
+    branches: [main]
   workflow_dispatch: {}
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
on:
push:
branches: [ main ]
workflow_dispatch: {}
on:
push:
branches: [main]
workflow_dispatch: {}
🧰 Tools
🪛 YAMLlint (1.37.1)

[warning] 3-3: truthy value should be one of [false, true]

(truthy)

[error] 5-5: too many spaces inside brackets

(brackets)

[error] 5-5: too many spaces inside brackets

(brackets)

🤖 Prompt for AI Agents 
In .github/workflows/update-progress.yml around lines 3 to 6, fix YAML lint
issues by removing the extra spaces inside the branch array and the unnecessary
empty mapping: change "branches: [ main ]" to "branches: [main]" and replace
"workflow_dispatch: {}" with a minimal, lint-friendly form (e.g.,
"workflow_dispatch:" without the empty braces) so the file passes YAML/linters
and avoids truthy/noise warnings.


permissions:
contents: write

jobs:
update-progress:
if: github.actor != 'github-actions[bot]'
runs-on: ubuntu-latest
steps:
Comment on lines +12 to +15
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

⚠️ Potential issue

Add concurrency control and drop the redundant recursion guard.

if: actor != github-actions[bot] plus [skip ci] is overkill. Use a concurrency group; keep the guard if you must.

 jobs:
   update-progress:
-    if: github.actor != 'github-actions[bot]'
     runs-on: ubuntu-latest
+    concurrency:
+      group: update-progress-${{ github.ref }}
+      cancel-in-progress: true
@@
-      - name: Push commit
-        if: steps.commit.outputs.changed == 'true'
-        run: |
-          git push
+      - name: Push commit
+        if: steps.commit.outputs.changed == 'true'
+        run: git push

Also applies to: 43-47

🤖 Prompt for AI Agents 
In .github/workflows/update-progress.yml around lines 12-15 (and similarly lines
43-47), replace the ad-hoc recursion/actor guard by adding a concurrency stanza
to the job (e.g., concurrency: { group: 'update-progress', cancel-in-progress:
true }) and remove the redundant "if: github.actor != 'github-actions[bot]'"
condition; if you want to keep a safety check, leave a minimal guard but prefer
the concurrency group to prevent overlapping runs.

- name: Check out repository
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'

- name: Recompute weighted progress
run: |
python3 scripts/update_progress.py
- name: Commit changes (if any)
id: commit
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add docs/features-ledger.md README.md
if git diff --cached --quiet; then
echo "changed=false" >> $GITHUB_OUTPUT
else
git commit -m "ci: update progress bars and KLoC [skip ci]"
echo "changed=true" >> $GITHUB_OUTPUT
fi
Comment on lines +39 to +41
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

[skip ci] may suppress other pipelines you actually want.

Consider dropping it or using a more targeted filter. Your anti-loop check already prevents recursion.

-            git commit -m "ci: update progress bars and KLoC [skip ci]"
+            git commit -m "ci: update progress bars and KLoC"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
git commit -m "ci: update progress bars and KLoC [skip ci]"
echo "changed=true" >> $GITHUB_OUTPUT
fi
git commit -m "ci: update progress bars and KLoC"
echo "changed=true" >> $GITHUB_OUTPUT
fi
🤖 Prompt for AI Agents 
.github/workflows/update-progress.yml lines 39-41: the commit message includes
"[skip ci]" which can inadvertently suppress other pipelines; remove "[skip ci]"
from the git commit -m string so the update commit doesn't skip CI, or if you
truly need to avoid running only this workflow use a more targeted mechanism
(e.g., add a workflow-specific conditional or path/branch filters) instead of
the blanket "[skip ci]".

- name: Push commit
if: steps.commit.outputs.changed == 'true'
run: |
git push
691 changes: 691 additions & 0 deletions AGENTS.md
View file
Open in desktop

Large diffs are not rendered by default.

43 changes: 43 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,14 @@ all: build
build:
GO111MODULE=on go build -ldflags "$(LDFLAGS)" -o bin/$(APP) ./cmd/$(APP)

Comment on lines 12 to 14
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Stop exporting GO111MODULE. It’s default since Go 1.16.

Trim noise.

-	GO111MODULE=on go build -ldflags "$(LDFLAGS)" -o bin/$(APP) ./cmd/$(APP)
+	go build -ldflags "$(LDFLAGS)" -o bin/$(APP) ./cmd/$(APP)
...
-	GO111MODULE=on go build -ldflags "$(LDFLAGS)" -o bin/tui ./cmd/tui
+	go build -ldflags "$(LDFLAGS)" -o bin/tui ./cmd/tui

Also applies to: 15-22

🤖 Prompt for AI Agents 
In Makefile around lines 12-14 (and similarly for lines 15-22), remove the
explicit GO111MODULE=on environment variable from the build and related targets;
update the commands to call go build (and other go commands) without prefixing
GO111MODULE=on so they rely on the default module behavior introduced in Go
1.16, leaving the rest of the flags and output paths unchanged.

.PHONY: build-tui tui-build
build-tui tui-build:
GO111MODULE=on go build -ldflags "$(LDFLAGS)" -o bin/tui ./cmd/tui

.PHONY: run-tui tui
run-tui tui: build-tui
./bin/tui --config=config/config.yaml

run:
./bin/$(APP) --role=all --config=config/config.yaml

Expand All @@ -23,3 +31,38 @@ tidy:

version:
@echo $(VERSION)

Comment on lines 32 to +34
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Add a progress target so humans don’t memorize the script path.

Make it easy.

 version:
 	@echo $(VERSION)
+
+.PHONY: progress
+progress:
+	python3 scripts/update_progress.py
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
version:
@echo $(VERSION)
version:
@echo $(VERSION)
.PHONY: progress
progress:
python3 scripts/update_progress.py
🤖 Prompt for AI Agents 
In Makefile around lines 32 to 34, add a new progress target that runs the
repository script so humans don't need to remember the path: define a progress
target that invokes the script (e.g., ./scripts/progress) and forward any
arguments, mark progress as .PHONY, and use an @ prefix to avoid Make echoing
the command; place the new target near the version target for discoverability.

.PHONY: hooks
hooks:
@git config core.hooksPath .githooks
@chmod +x .githooks/pre-commit
@echo "Git hooks enabled (pre-commit updates progress bars and stages docs)."

Comment on lines +35 to +40
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Add a proper clean target and stop leaving build trash around.

Also declare it PHONY.

 .PHONY: hooks
 hooks:
 	@git config core.hooksPath .githooks
 	@chmod +x .githooks/pre-commit
 	@echo "Git hooks enabled (pre-commit updates progress bars and stages docs)."
+
+.PHONY: clean
+clean:
+	rm -rf bin/*
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
.PHONY: hooks
hooks:
@git config core.hooksPath .githooks
@chmod +x .githooks/pre-commit
@echo "Git hooks enabled (pre-commit updates progress bars and stages docs)."
.PHONY: hooks
hooks:
@git config core.hooksPath .githooks
@chmod +x .githooks/pre-commit
@echo "Git hooks enabled (pre-commit updates progress bars and stages docs)."
.PHONY: clean
clean:
rm -rf bin/*
🤖 Prompt for AI Agents 
In Makefile around lines 35–40, there is no clean target and the PHONY
declaration is incomplete; add a proper "clean" target that removes common build
artifacts (e.g., build/, dist/, *.egg-info, .pytest_cache, .mypy_cache, .cache,
.venv, .coverage) using a safe recursive remove (rm -rf) so missing paths don’t
error, and add "clean" to the .PHONY list so the target is always run as a
recipe rather than a file.

.PHONY: mdlint
mdlint:
@if ! command -v npx >/dev/null 2>&1; then \
echo "npx not found. Please install Node.js to run markdownlint."; \
exit 1; \
fi
@npx -y markdownlint-cli2 "**/*.md" "!**/node_modules/**"

Comment on lines +41 to +48
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

🛠️ Refactor suggestion

Your lint targets ignore AGENTS.md and README.md. Fix scope.

mdlint-docs/mdlint-fix only hit docs/**/*.md. Expand to all markdown and add a Docker fallback guard.

-mdlint:
+mdlint:
 	@if ! command -v npx >/dev/null 2>&1; then \
 		echo "npx not found. Please install Node.js to run markdownlint."; \
 		exit 1; \
 	fi
-	@npx -y markdownlint-cli2 "**/*.md" "!**/node_modules/**"
+	@npx -y markdownlint-cli2 "**/*.md" "!**/node_modules/**"
 
-mdlint-docs:
+mdlint-docs:
 	@if ! command -v npx >/dev/null 2>&1; then \
 		echo "npx not found. Please install Node.js to run markdownlint."; \
 		exit 1; \
 	fi
-	@npx -y markdownlint-cli2 "docs/**/*.md"
+	@npx -y markdownlint-cli2 "docs/**/*.md"
 
-mdlint-fix:
+mdlint-fix:
 	@if ! command -v npx >/dev/null 2>&1; then \
 		echo "npx not found. Please install Node.js to run markdownlint."; \
 		exit 1; \
 	fi
-	@npx -y markdownlint-cli2 --fix "docs/**/*.md"
+	@npx -y markdownlint-cli2 --fix "**/*.md" "!**/node_modules/**"

Also applies to: 49-56, 57-64

🤖 Prompt for AI Agents 
Makefile lines 41-48 (also apply same changes to 49-56 and 57-64): mdlint target
and the mdlint-docs/mdlint-fix targets currently restrict globs to docs/**/*.md
and miss AGENTS.md and README.md; update the glob pattern to include all
markdown files (e.g., "**/*.md" while still excluding node_modules) and change
the prereq guard to try npx first and, if not present, fall back to running
markdownlint-cli2 via a docker node image (docker run --rm -v $(pwd):/work -w
/work node:... npx markdownlint-cli2 ...), ensuring the same logic is mirrored
in the mdlint-docs and mdlint-fix targets so no markdown files are skipped and a
docker fallback is available when npx is missing.

.PHONY: mdlint-docs
mdlint-docs:
@if ! command -v npx >/dev/null 2>&1; then \
echo "npx not found. Please install Node.js to run markdownlint."; \
exit 1; \
fi
@npx -y markdownlint-cli2 "docs/**/*.md"

.PHONY: mdlint-fix
mdlint-fix:
@if ! command -v npx >/dev/null 2>&1; then \
echo "npx not found. Please install Node.js to run markdownlint."; \
exit 1; \
fi
@npx -y markdownlint-cli2 --fix "docs/**/*.md"

.PHONY: mdlint-docker
mdlint-docker:
@docker run --rm -v "$(PWD)":/work -w /work node:20 \
npx -y markdownlint-cli2 "**/*.md" "!**/node_modules/**"
14 changes: 14 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,20 @@ Production-ready Go-based job queue system backed by Redis. Provides producer, w

See docs/ for the Product Requirements Document (PRD) and detailed design. A sample configuration will be provided in config/config.example.yaml once the implementation lands.

## Progress

For full details, see the Features Ledger at [docs/features-ledger.md](docs/features-ledger.md).

<!-- progress:begin -->
```text
██████████████████████▓░░░░░░░░░░░░░░░░░ 55%
------------|-------------|------------|
MVP Alpha v1.0.0
```
<!-- progress:end -->

----

## Quick start

- Clone the repo
Expand Down
103 changes: 103 additions & 0 deletions docs/audits/drift.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# Design–Implementation Drift Report

This report compares each feature spec in `docs/ideas/` against the current implementation under `internal/` and related code. It highlights alignment, gaps, and concrete next steps.

## Executive Summary

- Overall alignment score: 60.1/100 (Medium)
- Overall drift: 39.9%
- Scope: 37 feature specs reviewed; corresponding `internal/<feature>` modules scanned (handlers, logic, tests, and TODOs), plus TUI and Admin API integration points where relevant.

Key observations
- Foundation is strong: Admin API, tracing, exactly-once, storage backends, theme playground, terminal voice, and time-travel debugger are comparatively well aligned (low drift ≤25%).
- Productization gaps recur: runtime configuration endpoints, RBAC tie‑in, pagination at scale, and TUI wiring are the most common sources of drift.
- Several modules are substantial but not yet integrated into TUI flows or Admin API surfaces (e.g., rate limiting, DLQ UI depth, right‑click menus, patterned load).

Comment on lines +12 to +15
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Surround lists with blank lines per GFM.

Minor lint nit—fix it and move on.

-Key observations
+
+Key observations

Committable suggestion skipped: line range outside the PR's diff.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

12-12: Lists should be surrounded by blank lines

(MD032, blanks-around-lists)

🤖 Prompt for AI Agents 
In docs/audits/drift.md around lines 12 to 15, the consecutive list lines need
surrounding blank lines to conform to GitHub Flavored Markdown; insert an empty
line before the first list item and an empty line after the last list item so
the list is separated from surrounding paragraphs and lint will pass.

## Scoring Model

- We compute a feature Alignment Score (0–100) from code presence, tests, and obvious TODOs; Drift % = 100 − Alignment.
- Categories (by Alignment Score):
- Critical: 0–39 (very high drift)
- High: 40–59
- Medium: 60–79
- Low: 80–89
- Excellent: 90–100 (very low drift)

Heuristic inputs used for this pass: presence of `internal/<feature>` module, number of `.go` files and tests, explicit TODOs/WIP markers, basic route/handler availability, and TUI/Admin integration indicators found via grep. This is a fast quantitative baseline; targeted deep‑dives recommended for “High” and “Critical”.

## Critical Issues (Immediate Attention)

- Collaborative Session (Drift 80%): Minimal code, no tests, not integrated.
- Advanced Rate Limiting (Drift 60%): Strong core limiter present, but runtime Admin API controls and TUI widgets missing; producer/worker integration incomplete.
- Patterned Load Generator (Drift 60%): Handlers exist; patterns/scheduler/guardrails and TUI overlay not wired end‑to‑end.

## Detailed Findings by Category

- Low Drift (≤25%): admin-api, distributed-tracing-integration, storage-backends, time-travel-debugger, rbac-and-tokens, smart-retry-strategies, terminal-voice-commands, theme-playground
- Medium Drift (30–45%): exactly-once-patterns, multi-cluster-control, visual-dag-builder, automatic-capacity-planning, kubernetes-operator, producer-backpressure, event-hooks, job-genealogy-navigator, calendar-view, anomaly-radar-slo-budget, canary-deployments, chaos-harness, forecasting, json-payload-studio, job-budgeting, dlq-remediation-pipeline, dlq-remediation-ui, trace-drilldown-log-tail, worker-fleet-controls, right-click-context-menus, smart-payload-deduplication
- High–Critical (≥55%): multi-tenant-isolation, queue-snapshot-testing, advanced-rate-limiting, patterned-load-generator, collaborative-session

## Recommendations (Cross‑Cutting)

- Close the loop to TUI: For DLQ UI, rate limiting, patterned load, context menus — wire handlers into `internal/tui` and persist state where needed.
- Expose runtime controls via Admin API: Add update endpoints for limits, toggles, and policies; document OpenAPI and add tests.
- Pagination and guardrails: Ensure DLQ, list endpoints, and patterned load enforce bounds and use server‑side pagination.
- RBAC integration everywhere: Require tokens for sensitive ops; confirm deny‑by‑default semantics; add audit logs to destructive flows.
- Tests and docs: Add handler and e2e tests for newly exposed endpoints; update README/TUI docs with new keybindings and flows.

---

## Feature Drift Table

| Feature | Folder | Finished? | Drift % | Remarks | Recommendation |
| --- | --- | --- | ---:| --- | --- |
| admin-api | internal/admin-api | Yes | 20 | HTTP v1 endpoints (Stats, Keys, Peek, Purge DLQ/All, Bench) and middleware (auth, rate‑limit, audit, CORS, recovery) implemented; OpenAPI served; gRPC not present; TUI still mostly calls internal helpers directly. | Switch TUI Stats to Admin API; decide on gRPC scope (ship or de‑scope); expand CI integration tests; confirm deny‑by‑default tokens in all destructive routes. |
| advanced-rate-limiting | internal/advanced-rate-limiting | No | 60 | Redis Lua token bucket with priority fairness and tests in place; missing Admin API runtime updates, dry‑run preview endpoint, producer/worker integration, and TUI status widget. | Add Admin API CRUD for limits/weights; integrate with producer hints/worker throttling; surface TUI widget and metrics; document tuning. |
| anomaly-radar-slo-budget | internal/anomaly-radar-slo-budget | No | 45 | Handlers exist; metrics/alerts endpoints stubbed; thresholds/SLO budgets not clearly tuned; limited tests. | Define SLO config and thresholds; add Prometheus metrics; wire TUI “status/radar” widget; add calibration docs. |
| automatic-capacity-planning | internal/automatic-capacity-planning | No | 35 | Core structs and planner logic present; needs scheduler hooks and Admin API surface; limited integration tests. | Expose plan/apply/dry‑run via Admin API; add forecast inputs; e2e soak tests with patterned load. |
| calendar-view | internal/calendar-view | No | 35 | Routes and TUI helpers exist; TODOs for auth and multi‑queue filtering; pagination needs verification. | Add auth context, filters, and paging; connect to Admin API; add large‑list tests. |
| canary-deployments | internal/canary-deployments | No | 45 | Canary logic exists; limited production guardrails and rollback controls; minimal test coverage. | Add rollback/abort endpoints; audit logging; e2e with worker fleets. |
| chaos-harness | internal/chaos-harness | No | 45 | Fault injection scaffolding present; missing safety gates and observability glue. | Add scoped chaos profiles, RBAC, and kill‑switch; record effects to tracing/metrics. |
| collaborative-session | internal/collaborative-session | No | 80 | Minimal code; no tests; not wired to TUI. | Define protocol and permissions; add session host/guest modes; defer if out of scope this release. |
| distributed-tracing-integration | internal/distributed-tracing-integration | Yes | 20 | OTEL integration, trace propagation tests, and trace URL helpers implemented. | Link from TUI job views to external tracing UI; document configuration. |
| dlq-remediation-pipeline | internal/dlq-remediation-pipeline | No | 45 | Pipeline components present; classifier rules and auto‑retry policies limited; tests light. | Add rules engine, rate‑limited requeue, and safety bounds; expose via Admin API. |
| dlq-remediation-ui | internal/dlq-remediation-ui | No | 45 | API handlers (list/peek/requeue/purge) and TUI model exist; single test file; need pagination at scale and TUI polish; ensure Admin API parity. | Implement server‑side pagination and filters; expand tests; integrate with main TUI tab and keybindings; confirm RBAC/audit on destructive ops. |
| event-hooks | internal/event-hooks | No | 40 | Webhook plumbing in place; base URL TODO and health/status routes present. | Make base URL configurable; add signing/verification and retries; Admin API to manage subscriptions. |
| exactly-once-patterns | internal/exactly-once-patterns | No | 30 | Idempotency/outbox patterns implemented; some TODOs (hit‑rate calc, publishers). | Finalize metrics; add publisher adapters; document patterns and failure modes. |
| forecasting | internal/forecasting | No | 45 | Forecast stubs implemented; needs model selection and evaluation harness. | Provide baseline models (ARIMA/Prophet external or simple EMA); surface via Admin API and TUI. |
| job-budgeting | internal/job-budgeting | No | 45 | Budget manager, cost model, notifications present; limited tests and UI. | Add enforcement hooks and Admin API; TUI budget panel; alerting thresholds. |
| job-genealogy-navigator | internal/job-genealogy-navigator | No | 40 | Types and graph traversal present; non‑Go assets for views; integration unclear. | Expose via Admin API; TUI drill‑down; add pagination on lineage. |
| json-payload-studio | internal/json-payload-studio | No | 45 | Core handlers present; minimal tests; not fully plugged into TUI. | Add validation schemas, templates, and enqueue paths; TUI editor with previews. |
| kubernetes-operator | internal/kubernetes-operator | No | 35 | Operator scaffolding and tests exist; CRDs integration simulated. | Define CRDs; reconcile loops; e2e against kind; RBAC manifests. |
| long-term-archives | internal/long-term-archives | No | 45 | Archival hooks present; backends not fully pluggable; tests light. | Implement S3/ClickHouse adapters; retention/TTL policies; Admin API to export. |
| multi-cluster-control | internal/multi-cluster-control | No | 30 | Manager, errors, handlers, and many artifacts exist; compare/switch logic present; lots of non‑Go test assets. | Finalize e2e tests; wire to TUI tabs; Admin API for fan‑out actions with audit. |
| multi-tenant-isolation | internal/multi-tenant-isolation | No | 55 | Handlers with TODOs for RBAC validation; quotas/tenancy boundaries incomplete. | Enforce tenant authz middleware; define quotas and keys; add tests for isolation. |
| patterned-load-generator | internal/patterned-load-generator | No | 60 | Handlers exist; patterns/scheduling/guardrails and TUI overlay unproven; single test. | Implement sine/burst/ramp + stop/cancel; guardrails; profile save/load; chart overlay in TUI. |
| plugin-panel-system | internal/plugin-panel-system | No | 40 | Plugin lifecycle present; hot‑reload/sandboxing needs validation; non‑Go assets included. | Add permission model and sandbox; plugin SDK docs; TUI panel registry. |
| policy-simulator | internal/policy-simulator | No | 40 | Simulator with TODOs for retrieval/rollback; multiple tests present. | Wire Admin API preview/apply/rollback; persist scenarios; integrate with TUI. |
| producer-backpressure | internal/producer-backpressure | No | 35 | Backpressure scaffolding and tests; not hooked into rate limiter hints. | Integrate with advanced rate limiting; expose hints in client SDKs; metrics. |
| queue-snapshot-testing | internal/queue-snapshot-testing | No | 55 | Snapshot framework present with testdata; low code/test counts suggest early stage. | Expand differ coverage; add golden tests; docs for snapshot lifecycle. |
| rbac-and-tokens | internal/rbac-and-tokens | Yes | 25 | JWT manager, middleware, and handlers with tests; revoke and cache implemented. | Integrate with all sensitive Admin API routes; add per‑action scopes and audit trails. |
| right-click-context-menus | internal/right-click-context-menus | No | 50 | Zones/registry/menu implemented; TODO for focused item context; not wired into TUI tables. | Integrate with TUI table rows via bubblezone; add context actions and tests. |
| smart-payload-deduplication | internal/smart-payload-deduplication | No | 50 | Compression/dedup logic present with TODOs (dict build); limited integration. | Add dict training pipeline; expose dedup stats; integrate in enqueue path. |
| smart-retry-strategies | internal/smart-retry-strategies | Yes | 25 | Strategies and handlers implemented; metrics endpoint TODO; decent tests. | Implement Prometheus metrics; surface strategy selection in TUI; add docs. |
| storage-backends | internal/storage-backends | Yes | 20 | Multiple backends scaffolding present with tests; OpenAPI docs exist. | Complete adapter matrix; add conformance tests; document migration paths. |
| terminal-voice-commands | internal/terminal-voice-commands | Yes | 25 | Command mapping, handlers, and tests present; privacy/telemetry not addressed. | Add opt‑in, PII handling, and offline mode; short TUI tutorial. |
| theme-playground | internal/theme-playground | Yes | 25 | Theme system prototypes and tests; TUI integration partial. | Centralize styles; add theme toggle in Settings tab; docs for accessible palettes. |
| time-travel-debugger | internal/time-travel-debugger | Yes | 20 | Capture/replay and simple TUI implemented with tests. | Add selective replay controls; export/import; document guardrails. |
| trace-drilldown-log-tail | internal/trace-drilldown-log-tail | No | 45 | Trace ID plumbing present; log tail integration limited; tests partial. | Add tailing with filters; link TUI job to trace URL; privacy filtering. |
| visual-dag-builder | internal/visual-dag-builder | No | 30 | Orchestrator and types present; some .bak tests; not wired to enqueue pipeline. | Backend validation and DAG execution plan; TUI builder; Admin API to submit DAGs. |
| worker-fleet-controls | internal/worker-fleet-controls | No | 45 | Control handlers and audits exist; needs live graphs and safety checks. | Add pause/drain/resume with RBAC; per‑node metrics; TUI controls panel. |

---

## Methodology Notes

- Inputs: `docs/ideas/*.md` specs; `internal/<feature>` modules; grep for endpoints/routes, middleware, and TODOs; presence of tests and non‑Go assets; TUI and Admin API usage.
- Limitations: This pass uses heuristic signals and spot‑reads; it does not execute binaries or hit live services. High‑drift items should get a focused deep‑dive before scheduling.

## Next Steps

- Confirm priorities in AGENTS.md backlog; create tickets per “Recommendation” above.
- If desired, I can: (1) wire TUI to Admin API Stats, (2) add Admin API endpoints for rate‑limits, and (3) implement DLQ pagination + filters with tests.

Loading