projectbrain-Public/docs/UX_AUTONOMY_PRODUCT_CONTRACT.md

ProjectBrain UX & Autonomy Product Contract

Status: normative product contract

1. Product promise

ProjectBrain is a project operating system, not a collection of technical modules the user must operate manually.

The default user flow is:

User intent
  -> ProjectBrain understands context
  -> ProjectBrain prepares bounded work
  -> ProjectBrain executes what policy allows
  -> ProjectBrain validates
  -> ProjectBrain returns a result

ProjectBrain interrupts the user only when a real human decision is required.

2. User-facing mental model

The standard product vocabulary consists of five primary concepts:

1. Project — everything ProjectBrain knows and manages for one software project.
2. Opdracht — a requested outcome, investigation, fix, feature or improvement.
3. Beslissing — a choice ProjectBrain cannot responsibly make autonomously.
4. Resultaat — completed work plus understandable validation evidence.
5. Activiteit — the durable chronological record of what happened.

Technical domain objects remain valid internally but are not primary navigation concepts.

Internal concept	Default user presentation
Initiative	Opdracht / beslissing
Feature Delivery	Uitvoering van een opdracht
Review Queue	Jouw aandacht
Execution Feedback	Resultaat / bewijs
Context Pack	Internal AI context
Repository Intake	Automatic repository analysis
Repository Gap	Verbeterpunt / technical detail
Skill	Internal execution profile
Handoff	Internal transfer artifact
Session Pack	Internal execution artifact
Finding	Probleem / bevinding
Gitea Actions	Validation evidence
Build Loop	Technical orchestration diagnostics
Auto Mode controller	Technical autonomy diagnostics

3. Primary navigation contract

A normal project exposes exactly five primary destinations:

1. Overzicht
2. Opdracht geven
3. Jouw aandacht
4. Resultaten
5. Activiteit

Repository workbenches, findings, Build Loop, Auto Mode controller/runtime diagnostics, runtime readiness, architecture, source internals, skills, handoffs, audits and release evidence belong under Technische details.

A new standard feature MUST NOT add another primary project destination without changing this contract intentionally.

4. Canonical lifecycle and user work states

Every major subsystem projects its detailed state into the same seven-value canonical lifecycle. This is the machine-facing contract shared by the frontend and backend:

ready | running | waiting | needs_user | recovering | failed | done

The ordinary UI translates those values into the existing five concise user presentations where a separate queue, recovery or terminal-failure label would add noise:

• ProjectBrain werkt — ProjectBrain can proceed autonomously and execution is actually active.
• Jouw beslissing nodig — a real product, scope, credential, authorization or risk decision is required.
• Wacht op extern systeem — ProjectBrain is waiting for CI, repository, deployment, scheduled executor capacity or another external system.
• Geblokkeerd — work cannot safely proceed and no automatic recovery is currently possible.
• Klaar — the result and evidence are available.

ready means safe to start or claim, running means active execution is confirmed, waiting means an external step is pending, needs_user is a real human decision, recovering is bounded technical recovery, failed is a terminal or currently stopped path, and done means the committed result is available. Raw domain states such as approved, validating, pull_request_open, watch, current or pending may be shown only in technical details.

4.1 Auto Mode truth model

Auto Mode MUST expose three independent facts instead of collapsing them into one running label:

1. Desired state — Auto is on/off because the user enabled or disabled autonomous execution.
2. Operational state — a scheduled executor is connected/recent, stale or offline.
3. Work state — queued, working, waiting, retrying, needs-decision or completed.

enabled=true MUST NOT by itself be presented as active execution. A project with queued work and no recent executor must explicitly say that Auto is enabled but nothing is currently executing.

4.2 Single project-work authority

Normal project surfaces MUST derive their current work presentation from the same semantic resolver. At minimum Projecten, Overzicht, Opdracht geven and Jouw aandacht must agree on:

• whether a human decision is required;
• whether work is truly executing;
• whether work is waiting on an external system;
• whether a technical failure is in automatic recovery;
• whether work is merely queued;
• whether a verified result exists.

A list position or the first returned delivery MUST NOT be treated as the current task. Current work is selected by user-impact state first and recency second. A live human-decision state outranks technical activity; active execution outranks queued work; retryable recovery remains operational state rather than human attention.

Navigation chrome that does not load the live work resolver MUST link to Overzicht instead of inventing a potentially stale next action.

The current implementation authority is src/shared/lib/projectWorkState.ts. src/shared/lib/projectResume.ts owns project-entry priority and src/shared/lib/routeRegistry.ts owns the five primary project destinations. The backend emits the same lifecycle on Auto runtime summaries; these fields are projections of durable state, not a second persistence model.

5. Delegation and authorization policy

Default delegation mode: Autonoom uitvoeren.

Policy decisions:

LOW risk + reversible
  -> AUTO_ALLOWED

MEDIUM risk + reversible
  -> AUTO_ALLOWED_WITH_AUDIT

HIGH risk
  -> USER_DECISION_REQUIRED

DESTRUCTIVE / irreversible
  -> USER_DECISION_REQUIRED

A delivery with approvalState=approved is already authorized by ProjectBrain policy. Clients MUST NOT ask the user for another approval.

A delivery with approvalState=pending MUST NOT start repository writes.

Auto Mode exposes four ordinary profiles: Voorzichtig, Normaal, Autonoom and Aangepast. The first three select bounded, persisted run settings; individual retry, lease, brainstorm and run-budget controls remain under Advanced. Profile selection never bypasses risk or authorization policy.

start_feature_delivery and equivalent write paths must fail closed when policy authorization is absent.

5.1 Auto Mode executor host invariant

The primary Auto Mode executor surface MUST be scheduled tasks in the ordinary ChatGPT web chat with the ProjectBrain Autonomous Loop plug-in attached. Multiple such tasks MAY run concurrently when each owns a different ProjectBrain project.

The following are explicitly not supported as the Auto Mode scheduler or primary executor:

• Codex desktop or Codex CLI automations;
• ChatGPT Work tasks;
• a local background agent or local cron job;
• a server-side OpenAI API call;
• an alternative model provider silently substituting for ordinary ChatGPT web chat.

Codex may remain a development or administration tool, but MUST NOT own, wake, or impersonate the production Auto Mode execution loop. A change that moves scheduling away from ordinary ChatGPT web chat is an architecture change and requires an explicit update to this normative contract, its regression tests, and the production operating guide.

Each scheduled ChatGPT web run is only a wake-up. It MUST reload durable ProjectBrain state, generate one unique run_id, reuse that ID for every claim in the run, and stop at the configured item/time budget or an earlier terminal, busy, blocked, or human-decision state. ProjectBrain MUST enforce both budgets durably on the server; prompt compliance alone is insufficient.

ProjectBrain MUST refresh the matching working heartbeat automatically whenever the run claims or reports work. This keeps ordinary progress observable without spending separate ChatGPT tool calls on redundant keepalives. The run MUST send an explicit heartbeat with its active project only at startup, shutdown, and immediately before and after an external wait that can exceed five minutes. ProjectBrain MUST fence heartbeat ownership per active project and run_id: ordinary ChatGPT web tasks may execute different projects concurrently, one run cannot switch projects, overlapping runs cannot replace a current owner of the same project within that project's configured maximum run window plus a bounded grace period, delayed terminal heartbeats from another run are rejected, and the MCP claim boundary MUST reject a run that does not own an accepted working heartbeat for that project.

Routine Auto Mode MCP responses MUST be context-bounded. State reads default to a summary of the current phase and bounded recent evidence; claim/report responses MUST NOT echo the full roadmap, imported Markdown or completed-lease history. A full state read is an explicit diagnostic action, never the default scheduled-loop path.

Portfolio scheduling MUST remain starvation-free. Among claimable projects, the project with the oldest recorded run is returned first and a project that has never run precedes one that has. Backlog size MAY break an equal-age tie but MUST NOT let one large roadmap monopolize the ordinary ChatGPT web executor. Busy and blocked projects remain ordered after claimable work.

Transient infrastructure, network, validation, runner or provider failures MUST be recorded as retryable technical blockers with bounded exponential cooldown. Repeated technical failure MAY increase cooldown and diagnostic severity, but MUST NOT silently become a human blocker merely because a retry counter was reached. Missing credentials, required approval, destructive-risk decisions and genuine owner/product decisions are human blockers and may only be cleared explicitly.

Human-blocker classification is server-authoritative. Client/model supplied labels are compatibility hints only and MUST NOT be able to turn an ordinary technical failure into a human chore. A human blocker requires positive evidence of credentials, authorization, destructive or irreversible risk, or a genuine owner/product choice. Unknown operational failures fail toward retryable recovery, not toward human escalation.

A report for an expired lease MAY be accepted only when its exact token is still the active token and no later executor has reclaimed the work. This prevents completed long-running work from being discarded without allowing a stale executor to overwrite a newer claim. Report persistence MUST be idempotent by lease token and SHOULD automatically retry a bounded optimistic-concurrency collision before surfacing an error.

Autonomy persistence MUST update only the autonomy state path atomically. Unrelated WorkspaceState changes MUST be preserved. Auto writes use the persisted Auto updatedAt as their optimistic compare-and-swap boundary so unrelated project updates no longer create false Auto conflicts while concurrent Auto writers are still fenced.

An individual run MUST NOT pause, disable, delete, reschedule, or otherwise mutate its own recurring ChatGPT task. A ProjectBrain blocker is durable project state, not scheduler state. The recurring Chat task stays enabled, reports the blocker once when actionable, and checks durable state again on its next scheduled wake-up.

Explicit new user assignments outrank speculative brainstorm work and older unclaimed roadmap work in the current claimable phase. A clear phase with concrete work items SHOULD execute those items before an optional convergence brainstorm; an empty or genuinely ambiguous phase MAY brainstorm first.

Human-decision examples

Escalation is appropriate for:

• destructive or irreversible data loss;
• high-impact production changes;
• credentials, secrets or security-policy changes;
• a significant scope change;
• mutually valid product directions with no objective preference;
• ambiguity that cannot be resolved from repository or project context.

Escalation is not appropriate merely because ProjectBrain needs to:

• create a branch;
• create or update a low/medium-risk plan;
• choose internal context;
• select execution profiles;
• create a handoff or execution package;
• run tests;
• open a pull request;
• collect execution evidence;
• retry a transient network, runner, CI or provider problem.

6. Single user-facing next-action resolver

The standard next-action priority is:

1. real blocker requiring human action;
2. explicit human decision;
3. active work ProjectBrain is actually performing;
4. automatic retry/wait state;
5. relevant project warning;
6. invite the next user intent.

Build Loop, first-run walkthroughs, Auto Mode controller internals and release-readiness gates are not independent user-facing next-action authorities.

Release readiness may only dominate when the requested outcome is actually release/deployment related.

7. Repository-as-source invariant

A linked repository is primary technical source evidence.

The user MUST NOT be told to add source material or import repository state merely because the separate source library is empty.

Git sources should be synchronized automatically on project onboarding and refreshed through repository synchronization/webhook flows.

The user-facing Source Library is therefore Extra bronnen: only material that is not already available in the repository.

8. Capability truth

A reachable connector does not imply full operational readiness.

User-facing capability claims require positive evidence:

canAnalyze = project data + AI integration + repository linked
canModify  = canAnalyze + confirmed repository write access
canDeliver = canModify + confirmed validation capability
canDeploy  = canDeliver + confirmed deployment capability

Unknown capability must remain unknown; it must not be presented as green by default.

Technical connector names and URLs belong under Settings or Technical details.

9. Progressive disclosure

Every normal page should follow these rules:

• one dominant purpose;
• one primary CTA;
• one dominant user state;
• technical identifiers hidden by default;
• evidence translated to user impact first;
• raw branches, SHAs, runner names, lease tokens, run ids, validation commands and internal artifact ids remain available on demand.

Portfolio Home is a daily control surface, not an NOC. It shows human attention, real work, queue/recovery truth and recent project activity first. Runner capacity, Gitea Actions job lanes and worker internals belong under platform/technical management.

The project Overzicht begins with the confirmed current work state, its next safe action and the single human-attention summary. Recent verified results and a short human-readable history follow. Planning, health detail, graph detail and technical signals are available below that primary orientation, never as competing first-screen dashboards.

The Activity view is live-first: active execution, safe waiting/recovery and the next known step appear before recent completions. The durable chronological record remains available as an expandable timeline; raw actors, branches, job IDs, runners and queue data are technical evidence rather than the default story.

The Auto Mode controller begins with present control truth: desired state, actual work state, recovery or real human decision, and the next bounded action. Roadmap editing, detailed queue contents, retry/run limits and manual import are explicit advanced controls. Opening Auto Mode must not require the user to interpret a technical roadmap to understand what is happening.

Runtime begins with a compact capability summary grounded in health, readiness, repository, analysis and executor probes. Release operations, logs, diagnostics and raw infrastructure data follow through progressive disclosure. Settings groups ordinary controls by product capability and exposes connection permissions before low-level implementation values.

10. Onboarding contract

The start experience asks what the user already has:

• existing code;
• an idea;
• source material/documents;
• a new project from scratch.

Project setup then asks only for:

• what the project is;
• who it is for when relevant;
• the main desired outcome;
• an optional first useful result.

Stack, repository structure, documentation depth and execution profiles are inferred whenever possible and remain optional technical settings.

A selected repository is linked and synchronized as source evidence automatically.

11. Human attention inbox

Jouw aandacht is the only standard human-decision inbox.

It may contain:

• explicit high/destructive delivery decisions;
• blocked work requiring a human choice;
• missing credentials or owner authorization that ProjectBrain cannot safely infer;
• durable knowledge proposals that require acceptance;
• exceptional release decisions when release is the current goal.

Normal safe delivery planning and retryable technical recovery must not create user approval chores.

A human Auto blocker MUST be actionable from Jouw aandacht. The user must not have to discover the technical Auto controller merely to resume work after resolving the real human dependency.

12. Results and activity

A result should answer, in this order:

1. What did ProjectBrain accomplish?
2. What changed?
3. What was validated?
4. Is the result merged/verified/released?
5. What can the user do next?

merged is an implementation/delivery state, not by itself a proven result. The standard Resultaten view MUST count only verified or released work as completed results. A merged delivery that still lacks the required verification remains visible as waiting for verification and MUST NOT inflate result statistics.

Portfolio activity counts have the same truth rule: executing and validating are active work, draft/approved are queued, pull_request_open is external waiting, and merged is awaiting verification. These buckets MUST NOT be collapsed into a misleading “ProjectBrain werkt” total.

Technical evidence is expandable.

Activity's expandable history should read as a chronological project story. It must not displace active work, safe recovery or the immediate next step from the initial view. Audit-grade evidence and legacy history views stay available under technical history.

12.1 Cross-domain work graph and scope

Roadmap items, assignments, bugs, findings, remediations, recovery work, brainstorm suggestions, deliveries and release work MUST project into one durable work graph. Domain tables remain authoritative for domain-specific facts, but scheduling, dependency readiness, blocker inspection, leases, completion reports and audit history use the shared graph boundary.

Every graph node carries a stable identity, source, project, type, title, canonical and domain lifecycle, scope, priority, dependencies, risk, blocking state, execution eligibility, ownership/lease where applicable, attempts, timestamps, completion evidence and supersession relationships. Dependency mutation is durable and cycle-checked. Derived reconciliation MUST NOT delete explicit human dependency edits.

Scope is explicit:

• Required — necessary for correctness, security, release or an existing obligation.
• Committed — part of the current agreed objective.
• Stretch — useful but outside normal autonomous execution.
• Future — a suggestion or uncommitted possibility.

Auto Mode normally executes only Required and Committed work. A brainstorm suggestion MUST remain Future unless the user commits it or ProjectBrain promotes it because it is necessary to fix a defect/correctness issue, close a security or release blocker, or satisfy an existing committed requirement. The promotion reason remains auditable.

12.2 Completion and evidence

Each project MAY define an explicit Definition of Done containing required or optional requirements such as committed scope, green validation, UX verification, current documentation, release-candidate readiness, deployment, runtime verification and backup/rollback evidence. ProjectBrain MUST distinguish implemented, validated, merged, deployed, runtime-verified and actually complete.

Auto Mode MUST stop when the required Definition-of-Done requirements are satisfied. It MUST NOT invent improvement work to keep a completed project active. Evidence chains may connect requirement → work → delivery → commit → validation → pull request → merge → deployment → runtime verification. A missing stage remains missing; a completion report or raw commit does not fabricate validation, deployment or runtime evidence.

12.3 Truth, provenance and freshness

Project Knowledge is the user-facing consolidation of Project DNA, knowledge, memory, decisions, architecture, imported sources, requirements, documentation and generated execution context. Each important entry exposes type, source, authority, freshness, confidence where applicable, last verification, project area, conflicts and provenance. Context packs are generated execution snapshots and are not a manual operating queue.

Truth reconciliation uses an evidence hierarchy: verified runtime and repository evidence generally outrank verified evidence, approved knowledge, memory and roadmap descriptions. Safe stale-description conflicts MAY be reconciled automatically with provenance. Ambiguous or high-impact conflicts MUST become one deduplicated actionable attention item rather than several competing chores. Freshness is visible for repository sync, knowledge, runtime, analysis, delivery evidence, integrations and executor state; stale information MUST NOT look equally authoritative to fresh information.

12.4 Human attention and observability

Jouw aandacht aggregates decisions, approvals, critical or regressed findings requiring acceptance, knowledge conflicts, unrecoverable automation, capability/authentication issues, manual acceptance/review and high-risk operations. Root-cause keys batch duplicates. Technical retries, ordinary external waiting, queue depth and stale low-level metrics remain operational state until a genuine human action is required.

ProjectBrain MUST translate internal signals into user-oriented statements, for example “4 tasks are immediately runnable and 3 wait on dependencies” or “Automation has not reported progress for 8 minutes and recovery is being attempted.” Raw IDs, SHAs, leases, workers, API details and SLO measurements remain available under technical details.

12.5 Portfolio, pulse and command control

Portfolio Home is a compact command center with the sections Needs you, Running now, Recovering, Recently delivered, Stalled, At risk, Release ready and Autonomous coverage. These sections use canonical project/current-state semantics and are not independent status authorities. The initial viewport shows only non-empty priority lanes; secondary lanes, saved views, pulse and autonomous-coverage detail are discoverable below the daily triage surface rather than forming an empty card wall.

Saved views are persisted filters, not separate pages. Pulse summaries describe meaningful completed work, active work, new and resolved blockers, delivery/deployment/finding changes and the next likely action over recent, daily or weekly windows. Natural-language commands are parsed into objective, constraints, allowed scope, policy and requested completion state, then applied only through normal authorization, recovery and scheduling controls. An unrecognized command performs no mutation.

12.6 Diagnostics and safe recovery

ProjectBrain diagnostics MUST distinguish process, transport, authentication, authorization, API reachability, safe functional reads, write readiness, latency, latest successful probe and recent failure evidence. Connector health is not inferred from process/container health. The ProjectBrain path is represented as client → MCP hub → connector → ProjectBrain API → database whenever those dimensions are available; missing external probe capability remains unknown or degraded, not green.

The stuck detector checks stale heartbeats, expired leases, queues without consumers, runs without meaningful progress, runnable work that is not selected, stale delivery state, merged-but-active work and functional connector failures. Safe lease reclaim and state reconciliation happen automatically and leave audit evidence. Destructive writes are never used merely to prove connector health.

13. Compatibility strategy

Technical and legacy routes remain available during the migration, but are removed from primary navigation. Where a historic deep link contains technical filters, the application should preserve that intent by routing to the technical view rather than silently discarding parameters.

Compatibility must not force legacy terminology back into the primary UX.

Historical stabilization and post-audit documents are implementation history unless this contract or the current documentation index explicitly marks them active. They MUST NOT override the current product or autonomy contract during context resolution.

14. Acceptance criteria

The intent-first transformation is considered intact only when:

• a nontechnical user can create or import a project without understanding Git/MCP/CI internals;
• a linked repository is sufficient source evidence;
• a normal project has exactly five primary destinations;
• Auto Mode controller/runtime details do not become a sixth primary destination;
• a normal reversible delivery does not require manual approval;
• high/destructive work cannot start before a real user decision;
• backend authorization state and UI wording agree;
• Auto enabled is never confused with a connected executor or active work;
• Projecten, Overzicht, Opdracht geven and Jouw aandacht do not contradict one another about current work;
• retryable technical failures remain self-healing and do not become human chores merely because a retry limit was reached or a client labels them human;
• explicit user assignments outrank speculative autonomous work;
• ordinary next actions are not hijacked by Build Loop, Auto diagnostics or release gates;
• only verified/released delivery work counts as a normal user result;
• portfolio “working” counts exclude queued, externally waiting and merely merged work;
• unrelated project-state writes cannot overwrite the autonomy substate;
• result pages explain concrete changes and validation in plain language;
• technical evidence remains available without dominating the normal flow;
• automated tests enforce the navigation, state, recovery, result and capability contracts.