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.