This commit is contained in:
DevRunbook release export
@@ -0,0 +1,359 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user