DevRunbook-Public/docs/51-post-audit-product-roadmap.md

51 — Post-audit product roadmap

Purpose and governing principle

This roadmap governs work after the 2026-07-29 platform audit. It extends the completed MVP without weakening package, composition, authorization, integrity or evidence contracts.

The immediate priority is no longer feature expansion. DevRunbook must first become obvious for a user who thinks in terms of project + task. Codex execution, team governance and additional forge adapters remain blocked until the simple flow and release evidence pass their gates.

Phases are outcome-gated, not date-gated. A later phase may be explored for risk reduction, but cannot be declared complete before all earlier gates pass.

North-star outcome and measures

A first-time, non-technical user can find a project, describe a task in ordinary Dutch or English, understand what will happen and generate a useful safe task without seeing internal keys, schema types, package terms or generic composer remediation. The default path normally asks only for:

1. a project;
2. a task.

Expert controls remain available through progressive disclosure. Simplification may supply governed defaults and friendlier presentation, but cannot bypass server validation, policy precedence or deterministic rendering.

The release dashboard must track simple-flow completion and duration, expert-control usage, blocking findings, project-search success, repository freshness, executed/skipped test counts, accessibility violations, failed jobs, backup evidence and storage headroom.

Initial release targets:

• at least 90% of representative simple-flow fixtures generate from project + task alone;
• zero raw input keys, schema types or generic fallback text in simple mode;
• usable project selection with 500 repositories;
• zero required test suites reporting success when no tests executed;
• zero serious/critical accessibility findings in critical flows;
• exactly one primary main landmark per page;
• primary mobile controls have at least 44 by 44 CSS-pixel target areas;
• every repository count has a named scope and reconciles with source status.

Phase 9 — Release-gate stabilization

Status: Complete Outcome: local runtime and test evidence are trustworthy before product behavior changes.

Scope:

• reproduce and profile both @devrunbook/content timeouts on Node.js 24;
• remove repeated fixture/catalog work or use a test-owned immutable fixture cache where isolation remains proven;
• lengthen only measured, bounded test timeouts;
• provision or require disposable PostgreSQL for test:integration and fail when zero tests execute;
• report executed, skipped and failed integration counts separately;
• add one repository runtime marker (.nvmrc, .node-version or Volta) and fail preflight on the wrong Node major;
• align local, CI and container Node/pnpm contracts;
• move tooling out of production dependencies where applicable and upgrade, override or formally govern the transitive esbuild advisory;
• reconcile CURRENT_STATE.md with the existing Milestone 8 evidence.

Exit gate:

• format, lint, typecheck, unit, security and build pass on Node 24;
• formerly timing-out tests pass repeatedly without unexplained flakiness;
• all required PostgreSQL integration tests execute and pass;
• unavailable PostgreSQL produces a clear non-zero gate;
• pack validation and all 28 golden renders remain unchanged;
• remaining moderate advisories have reachability, owner and review date.

Audit findings: 13, 14, 15, 16 and 17.

Phase 10 — Two-choice simple task flow

Status: Complete Depends on: Phase 9
Outcome: project + task is sufficient for normal beginner journeys.

Scope:

• introduce a presentation-only Simple mode, distinct from governed work mode and autonomy;
• make targetFlows optional for usability work and supply a task-specific governed default such as the platform's primary user flows;
• map typed inputs to ordinary-language questions and examples;
• accept friendly chips, sentences or multiline lists and normalize them to the existing server contract;
• never display keys such as targetFlows or types such as string-list;
• ask follow-ups only when safety or usefulness cannot be resolved from project evidence or a declared safe default;
• replace generic lint/compatibility fallback text with task-aware recovery;
• review what will be inspected/changed, what is protected, how success is checked and what the user does next;
• keep the full composer behind “Adjust details” and record privacy-safe funnel metrics without task text.

Exit gate:

• usability, bugfix, feature, documentation and inspection fixtures complete from project + task whenever their safety contract permits;
• the audited Improve usability flow needs no manual targetFlows entry and shows no generic fallback;
• every default is visible in review with provenance;
• unsafe or ambiguous tasks still stop with a human-readable reason;
• Simple and Expert produce identical bytes for identical normalized inputs;
• desktop and 390-pixel browser gates cover keyboard and all recovery states.

Audit finding: 1 and the audit's central conclusion.

Phase 11 — Scalable project selection and real identity

Status: Complete Depends on: Phase 10
Outcome: users quickly find the right project and recognize their account.

Scope:

• add project search, recent projects, favorites and last-used selection;
• show at most five initial suggestions behind an “All projects” expansion;
• rank by recent Gitea activity with deterministic fallback ordering;
• preserve selection state across refresh and return;
• expose named states: found, imported, analyzed, stale and unavailable;
• safely import on selection when a discovered project lacks a local profile;
• show authenticated name/email, derived initials and role separately;
• link account, password and session management from the account menu;
• enforce workspace authorization on recents, favorites and imports.

Exit gate:

• keyboard/responsive tests pass with 0, 5, 31 and 500 repositories;
• recent, favorite and search ordering is deterministic;
• API and UI counts reconcile with an explanation for every difference;
• verified account data never falls back to generic identity;
• cross-workspace selection, favorite and import attempts are denied.

Audit findings: 2, 6 and 7.

Phase 12 — Plain-language navigation and localization

Status: Complete Depends on: all Now phases
Outcome: the default interface needs no development or AI vocabulary.

Scope:

• add persistent Simple and Expert presentation modes without duplicating domain behavior;
• default primary navigation to Start, My tasks and Projects;
• group Library, Collections and Prompt Lab under an advanced “More” area;
• place operations and integration administration under role-gated Management;
• maintain a governed copy dictionary mapping technical concepts to plain labels while preserving exact terms in Technical details;
• add Dutch and English, browser-language detection and account preference;
• translate onboarding, simple composition and recovery errors first;
• show local dates/times while retaining UTC contracts/storage;
• test missing translations and draft preservation across mode/language changes.

Exit gate:

• beginner testing completes the north-star journey without explaining playbooks, packages, digests, autonomy or governance;
• users see only role-appropriate primary navigation;
• critical flows pass in Dutch and English, including validation errors;
• Expert retains provenance, digest, policy and quality detail;
• language or mode changes do not lose the active draft.

Audit findings: 3, 4, 8 and the user-facing portion of 22.

Phase 13 — Continuous repository freshness

Status: Complete Depends on: Phase 11
Outcome: project context stays current with little operator work.

Scope:

• schedule Gitea discovery/snapshot jobs through the PostgreSQL worker;
• add “Refresh all” and per-project refresh with idempotent progress;
• detect default-branch and allowlisted-evidence changes before full analysis;
• import an eligible missing profile when selected;
• show friendly freshness with exact time in Technical details;
• warn only when staleness can affect the selected task;
• preserve last-known-good snapshots on failure;
• threat-model optional signed, replay-resistant, rate-limited Gitea webhooks;
• retain read-only forge access.

Exit gate:

• scheduled jobs survive restart, avoid duplicates and back off safely;
• meaningful evidence changes create reviewable snapshots while unchanged projects do not churn profiles;
• freshness and counts reconcile across Start, Projects and Settings;
• outage, permission, rate-limit and stale-context states are actionable;
• any webhook passes signature, replay, flood and workspace-isolation tests.

Audit findings: 5 and 6.

Phase 14 — Accessibility and interaction regression

Status: Complete (2026-07-30) Depends on: Phases 10–12
Outcome: the redesigned app is robust with keyboard, touch and assistive technology.

Scope:

• keep the app shell as the only page-level main;
• use labelled sections/articles below it;
• keep one interactive control per input and remove hidden expert controls from the accessibility tree;
• associate each label, description and error directly with its control;
• make full project/task cards operable with visible focus;
• enforce 44 by 44 target areas for primary mobile actions;
• add axe coverage for Start, composer, Projects, My tasks, account and Management;
• run screen-reader smoke, zoom/reflow, contrast, reduced-motion and touch checks.

Exit gate:

• critical pages have one main and no duplicate controls;
• no serious/critical automated accessibility violations;
• critical actions are keyboard-complete with correctly announced status;
• 200% zoom, 390 pixels and both themes have no blocking clipping;
• exceptions name owner, user impact and review date.

Audit findings: 9, 10, 11 and regression protection for 12.

Phase 15 — Human operations and deployment hardening

Status: Complete (2026-07-30) Depends on: Phase 9; may run alongside 13–14 with separate file ownership
Outcome: operators see health and recovery needs; ordinary users do not see raw administration detail.

Scope:

• summarize operational outcomes and prominent failures; move UUIDs, attempts and raw UTC to Technical details;
• add safe retry and plain-language problem actions;
• surface app/schema version, last observed successful backup, database/artifact size, disk headroom, last Gitea sync and failed jobs;
• distinguish observed backup evidence from external success the app cannot prove;
• verify HTTPS reverse-proxy, trusted-proxy and secure-cookie behavior and document trusted-LAN-only HTTP;
• suppress unnecessary framework disclosure where compatible;
• enforce/document capability drop, PID limits and recommended memory limits;
• assess read-only all-in-one root filesystem with explicit writable mounts or tmpfs, and minimize the root supervisor boundary;
• add storage-pressure guidance and actionable degraded states.

Exit gate:

• only authorized roles reach management operations;
• the dashboard clearly answers whether app, worker, database, storage, backup evidence or Gitea needs attention;
• container limits and writable paths are verified on Unraid/Compose;
• HTTPS produces secure cookies and documented headers;
• backup-age and disk-pressure warnings never claim unobserved success.

Audit findings: 18–23.

Phase 16 — Post-audit release qualification

Status: Complete (2026-07-30; release tag awaits operator approval) Depends on: Phases 9–15
Outcome: a release candidate proves technical correctness and beginner usability.

Scope and gate:

• run the complete quality gate on the supported runtime;
• execute all PostgreSQL integration tests with non-zero assertions;
• run Playwright and accessibility suites in both languages and modes;
• repeat clean-room install, restart, upgrade, backup and restore;
• re-audit the project + task journey with a non-technical fixture;
• reconcile every audit finding and acceptance criterion to evidence, limitation or accepted exception;
• update CURRENT_STATE.md, machine-readable evidence, FINAL_HANDOFF.md, release notes and operator docs;
• require the targets in this document, no unexplained skipped critical tests, no unresolved critical/high product security finding and no blocking beginner-flow/accessibility/operations defect;
• create a release tag only after operator approval.

Strategic expansion after release qualification

Phase 17 — Codex-native exports

Governed AGENTS.md builder, Codex Skill/plugin-compatible export, optional read-only MCP search/fetch/generate and supported deep-link/handoff metadata. Start only after current official Codex contracts are verified. No direct execution is introduced.

Phase 18 — Controlled local execution bridge

Local companion/CLI, worktrees, exact prompt handoff, explicit approvals, streaming state, cancel/retry/cleanup and signed result evidence. Requires a new threat model, ADR and independent isolation/credential/security review. The web application must not gain arbitrary remote execution.

Phase 19 — Teams and governance

Shared workspaces, membership, review/approval, workspace policy, shared profiles, private registries, OIDC/SSO, retention and signed internal releases. Requires a proven authorization matrix for every shared resource.

Phase 20 — Multi-forge and ecosystem

GitHub, GitLab and Forgejo adapters, normalized capability/freshness behavior, a non-executable connector boundary, curated registry imports, signatures and trust roots. Every adapter must preserve SSRF, redaction, least-permission, outage and last-known-good guarantees.

Phase 21 — Isolated evaluation runner

Disposable fixture environments, controlled Codex orchestration, protected-path/diff checks, command evidence, regression dashboards, operator review and cost/duration reporting. Requires Phase 18 plus an independently verified isolation, budget and teardown design.

Explicit deferrals

• vector search or a vector database;
• public ratings marketplace;
• unreviewed AI-authored package publication;
• Kubernetes as a required target;
• arbitrary server-side plugin or repository command execution;
• direct forge writes, automatic merges or write-enabled web containers;
• billing/commercial multi-tenancy and native mobile applications.

Audit traceability

Findings	Owning phase	Primary evidence
1	10	Two-choice fixtures and copy assertions
2, 6, 7	11	500-project, count and identity tests
3, 4, 8	12	Mode, role and bilingual browser matrix
5, 6	13	Scheduled refresh, freshness and outage tests
9–12	14	Landmark, label, target-size, axe and screen-reader checks
13–17	9	Node 24 and non-zero test/dependency evidence
18–23	15	Security, container, HTTPS and operations evidence
All	16	Re-audit and complete release evidence

Delivery discipline

Every phase follows CODEX_EXECUTION_PROTOCOL.md, updates CURRENT_STATE.md and links audit/requirement IDs to evidence. User-facing phases require browser verification. Schema, package, catalog, API, fixture or composer changes require pack validation and the reference-composer check before and after. Golden bytes change only through an explicit compatibility decision and source regeneration.