Forge user stories

As a user, I can move among every Forge domain without losing my current identity or confusing domain hierarchy.

Where it lives

App shell, desktop navigation, mobile navigation, route catalog.

Current evidence and next check

the Action Bar now searches all 29 primary routes; complete every destination, active-state, back-path, and permission-state check.

As a user, I can scroll into content while the authored top bar compresses smoothly, retains its primary controls, and fully reopens at the top.

Where it lives

Desktop and mobile app shell plus the top-bar collapse controller.

Current evidence and next check

124 px desktop and 96 px mobile ranges, measured forward/reverse curves, stable expanded content, and clean 41-frame stress passes at both viewports.

As a user, I can complete the same core workflow on phone and desktop without overflow, occlusion, or a desktop-only control.

Where it lives

All web routes and guided dialogs.

Current evidence and next check

maintain a route-by-route 390 x 844 and desktop matrix.

As a user, I can choose any supported theme and every surface, image, graph, map, menu, and dialog updates coherently.

Where it lives

Theme system, CSS semantic tokens, canvas/map/graph renderers, theme settings.

Current evidence and next check

full light/dark route matrices pass; complete accessibility contrast sampling remains.

As a user, I see an immediate, truthful route-loading state and then useful primary content without a blank or artificial wait.

Where it lives

Route Suspense boundaries, API query scheduling, page states.

Current evidence and next check

Overview no longer holds compact health and movement reads behind a fixed delay; Home routes settle in 0.44-1.19 s after warm-route navigation. Continue the full route matrix.

As a user, I can scroll long or visually rich views without flashes, disappearing content, unstable images, or layout shifts.

Where it lives

Virtualized lists, graphs, timelines, image fallbacks, sticky/fixed shell elements.

Current evidence and next check

shell, graph, and the 100-event Activity archive pass bidirectional stress checks; continue the remaining long-route matrix.

As a user, I receive useful loading, empty, partial, offline, and error states instead of broken pages or silent controls.

Where it lives

Shared page-state components, mutation feedback, API error envelopes.

Current evidence and next check

shared loading, empty, and error states expose truthful live-region semantics; complete partial/offline and route-wide failure fixtures.

As a user, I can create or act on the relevant record from the global Action Bar without navigating through unrelated pages.

Where it lives

Action Bar, entity create registry, global commands.

Current evidence and next check

explicit mobile/desktop close and all-primary-route discovery pass; complete per-entity permission, create, and return-path checks.

As a user, I create or edit complex records through the established ModalBase guided flow, with only missing or ambiguous questions shown.

Where it lives

Guided dynamic modal forms, question-flow dialogs, domain-specific steps.

Current evidence and next check

guided flows can now keep a user on the current step with visible missing-answer guidance, and goal/project identity checks use it before later optional steps. Complete every create/edit contract comparison; side-panel replacement forms remain regressions.

As a keyboard user, I can search routes and records, run commands, and return to my previous context.

Where it lives

Command palette, global search, focus restoration.

Current evidence and next check

close restores focus to the exact shell trigger and all primary routes are searchable; complete ranking, shortcut, record, and mobile-alternative checks.

As a multi-user operator, I can see and change the active user scope and understand whose records I am viewing or editing.

Where it lives

User scope selectors, ownership fields, API scope policy.

Current evidence and next check

the real shell selector now names the active scope, exposes pressed states and a labeled option group, meets the phone tap target, and avoids duplicate category/user choices when only one user belongs to a category. Complete filtered write, empty-scope, token, and bot-identity matrices.

As a user, I can link any compatible Forge entity to another through the general relationship model and inspect the connection from both sides.

Where it lives

General entity links, link pickers, backlinks, Knowledge Graph.

Current evidence and next check

batch linkedTo search now includes indexed general relationships in both directions while preserving ownership filters and response bounds. Complete every entity family, duplicate prevention, unlink, permission, and deleted-target matrix.

As a user, I can pin important records and return to recently viewed records without unbounded lists.

Where it lives

Action Bar pins, recent records, entity_navigation.

Current evidence and next check

recent resolution now scans 250-row batches within a hard 1,000-row budget, so a stale first batch no longer hides valid recents; the 5,000-row bound remains fast. Complete pin stale-target, cross-actor, touch restriction, and UI return-path matrices.

As a keyboard or assistive-technology user, I can operate navigation, dialogs, boards, graphs, lists, and status updates.

Where it lives

Focus system, ARIA names/live regions, reduced motion.

Current evidence and next check

named compact controls, Action Bar focus return, page-state announcements, and reduced-motion reward receipts pass; complete the remaining workflow matrix.

As a returning user, I keep the visual identity, information density, motion, mascot, trophies, and authored conveniences that make Forge recognizable.

Where it lives

Shell animation, Smith imagery, Trophy Hall, transitions, dense work surfaces.

Current evidence and next check

regression tests now cover the mobile shell and trophy visibility; extend feature-retention fixtures.

As a user, I can save a cross-domain search, scope, and filter combination as a named view and return to the same bounded result later.

Where it lives

Action Bar, route filters, user-scoped saved-view contract.

First evidence needed

observe repeated manual filter sequences, define ownership and permission behavior, and prove that saved state survives route and schema changes safely.

As a user, I can create a related record from my current context with the valid relationship prefilled and return to the exact place I started.

Where it lives

Action Bar, guided create flows, general entity links, return-state contract.

First evidence needed

measure current create-and-return steps in at least five story families and test ambiguous, unauthorized, deleted, and stale source records.

As a user, I can undo a recent reversible change through a bounded receipt without hiding changes that cannot be safely reversed.

Where it lives

Mutation receipts, soft delete, board moves, dismissals, metadata edits.

First evidence needed

inventory reversible mutations and define expiry, idempotency, authorization, concurrency, and honest non-reversible states before exposing a shared control.

As a user, I can see when important derived information was updated, where it came from, and whether it is partial or stale.

Where it lives

Shared provenance presentation, Overview, Health, Movement, Life Force, Watch snapshots.

First evidence needed

map every source timestamp and partial-data rule, then confirm that a shared treatment adds clarity without duplicating stronger domain-specific labels.

As a user, I can review suggested relationships between records, understand why each link was proposed, and accept or reject it before Forge writes anything.

Where it lives

General entity links, Knowledge Graph, suggestion and explanation contract.

First evidence needed

establish precision and false-positive thresholds, privacy boundaries, permission filtering, and a no-write-until-confirmed test matrix.

As a user, I can queue supported web changes while temporarily offline and later see whether each change was accepted, conflicted, or needs my decision.

Where it lives

Web shell, mutation outbox, idempotency keys, conflict receipts.

First evidence needed

audit mutation idempotency and conflict behavior, define an explicit supported-action list, and test reconnect, duplicate, stale, and multi-device cases.

As a user, I can capture text, links, files, or dictation in one place, review the record type and relationships Forge proposes, and confirm the result before it is stored.

Where it lives

Global capture, Artifact Store, notes, guided classification, general links.

First evidence needed

test representative inputs, ambiguous classifications, unsafe files, permissions, accessibility, and a strict confirmation boundary.

As a user, I can open Forge and immediately understand today's priorities, active work, health context, recent evidence, and momentum.

Where it lives

overview, operator overview/context APIs.

Current evidence and next check

isolated first-use and active-work fixtures plus the live data-rich store pass at 390 x 844 and 1280 x 720; empty health is truthful and optional reward setup does not block entry.

As a user, I can arrange the overview around the signals I care about without losing required modules after upgrades.

Where it lives

Overview layout registry and persisted layout.

Current evidence and next check

migration, required-widget restoration, breakpoint scaling, persisted route round-trip, reset, and compact control naming pass; complete direct drag/reorder QA.

As a user, I see Smith, current progression, streak pressure, and a real earned or next trophy in the first overview viewport.

Where it lives

Overview gamification widget and asset route.

Current evidence and next check

trophy request is primary, sprite route is independent of web-dist discovery, and fallback catalog is non-empty.

As a user, I can review a bounded queue of decisions, blocks, failed syncs, and runtime problems, then snooze, dismiss, restore, or follow the valid action.

Where it lives

attention-index, dedicated attention_inbox routes.

Current evidence and next check

empty and 12-item live states, allowed-action rendering, snooze/dismiss/restore, actor scope, stale-evidence invalidation, and bounded pagination pass.

As a user, I can inspect a chronological audit trail of meaningful entity, task, agent, and sync activity.

Where it lives

activity-index, activity/event APIs.

Current evidence and next check

empty and 100-event live states, source attribution, correction hiding, and a 44-frame full-list mobile traversal pass; complete filter/redaction checks.

As a user or trusted agent, I can store an evidence-backed insight and connect it to the records it explains.

Where it lives

insights-index, insight, general entity links.

Current evidence and next check

the three-step guided flow, read model, provenance, linked-record lifecycle, feedback, and read-back pass; complete deduplication checks.

As a user, I can close a week by reviewing outcomes and evidence, then choose the next execution focus.

Where it lives

weekly-review, planning/health summaries.

Current evidence and next check

empty and data-rich responsive states plus idempotent finalization and one-time reward evidence pass; complete explicit cross-week boundary fixtures.

As a user, I can follow one valid action from an attention item and see evidence that the underlying problem was resolved rather than merely dismissed.

Where it lives

Attention Inbox, action routes, resolution receipts, activity evidence.

First evidence needed

audit every attention kind, allowed action, authorization rule, stale-item condition, and verifiable resolution signal.

As a user, I can open a concise daily briefing that explains what matters now using current work, schedule, health context, and recent evidence without inventing conclusions.

Where it lives

Overview, Today, calendar, health context, activity, provenance.

First evidence needed

define source freshness and omission rules, test empty and conflicting evidence, and compare comprehension with the existing Overview and Today surfaces.

As a user, I can create a goal that states the desired direction, why it matters, ownership, horizon, and relevant links.

Where it lives

goals-index, goal, guided create flow.

Current evidence and next check

the guided flow now blocks progression until the missing goal name is supplied, keeps defaults intact, and passes live 390 x 844 layout/error QA. Complete rich creation, agent questions, update, delete, restore, and link matrices.

As a user, I can inspect one goal's purpose, progress, strategies, projects, notes, links, and execution history.

Where it lives

goal-detail.

Current evidence and next check

goal detail now mounts projects in eight-item batches with an exact visible/total status and bounded expansion, preventing dense goals from crowding phone navigation. Complete strategies, linked counts, stale links, evidence ordering, and full mobile hierarchy matrices.

As a user, I can define and edit a strategy as an ordered graph of states, dependencies, and linked work.

Where it lives

strategies-index, strategy-detail, strategy, graph editor.

Current evidence and next check

graph validation now rejects duplicate edges and cycles iteratively at large depth; the sequence editor supports keyboard sorting, bounded undo history, Ctrl/Cmd+Z outside text fields, and filling the initial placeholder without duplicate nodes. Complete full API round-trip, redo, corrupted persisted graph, and dense live-graph performance matrices.

As a user, I can create a project with a concrete outcome, PRD, ownership, lifecycle, scheduling rules, and links.

Where it lives

projects-index, project-detail, project.

Current evidence and next check

the guided flow blocks missing goal/title answers at the relevant step and replaces the mobile-hostile native assignee multi-select with bounded searchable checkboxes and a selected count. Complete PRD editing, scheduling, pause/restart/complete, and link matrices.

As a user, I can inspect the full execution hierarchy from goals through strategies, projects, issues, tasks, and subtasks.

Where it lives

project-hierarchy.

Current evidence and next check

hierarchy construction now preserves every project work item exactly once even when parent references are missing or cyclic, with focused mixed orphan/cycle coverage. Complete persisted collapse state, dense-tree performance, and live corrupted-data fixtures.

As a user, I can move projects, issues, tasks, and subtasks through one Kanban board without losing type or hierarchy.

Where it lives

kanban-index, task/project status mutations.

Current evidence and next check

move paths now share optimistic rollback and accessible failure receipts; complete keyboard move, hierarchy, and dense-board matrices.

As a user, I can create and update a concrete task with instructions, owner, hierarchy, timing, status, evidence, tags, and links.

Where it lives

task-detail, task, guided task flow.

Current evidence and next check

task assignees now use the same bounded searchable checkbox control as projects, with explicit owner-versus-contributor copy and clear-all behavior. Complete all task kinds, parent rules, due-time zones, delete/restore, and agent read-back.

As a user or trusted agent, I can start, heartbeat, focus, complete, or release a real task run instead of pretending status means active work.

Where it lives

task_run action routes and task-run controls.

Current evidence and next check

bounded controls cover claim, heartbeat, focus, completion, release, stale leases, and offline errors; complete conflict, idempotency, and handoff matrices.

As a user, I can record truthful signed time corrections when work occurred without a live run.

Where it lives

work_adjustment, operator context.

Current evidence and next check

the mutation now submits the exact clamped signed delta shown to the user; complete attribution and aggregate-recalculation checks.

As a user, I can plan a task into time, see its current pressure, and keep the calendar and task state connected.

Where it lives

task_timebox, calendar, task detail.

Current evidence and next check

the source package now covers bounded owner-scoped suggestions and manual placement, IANA timezone and DST handling, overlap and concurrent mutation control, provider projection and durable delete retries, bounded generic search, guided calendar flows, complete direct routes and OpenAPI, and aligned OpenClaw and Hermes helpers. API lifecycle tests are 12/12 and shared Psyche/Preferences delete regressions are 9/9; packaged migration 091 and authorized desktop/phone visual validation remain.

As a user, I can choose the next useful work for today using urgency, schedule, capacity, and active context.

Where it lives

today-index, operator context, Life Force and calendar reads.

Current evidence and next check

one deterministic owner-scoped decision now drives the Today page, direct API, and operator recommendation. Active work, schedule, urgency, AP capacity, overload, no-work, stale evidence, timezone/DST behavior, bounded candidates, explanatory reasons, and blocked-work suppression are covered; OpenClaw, Hermes, onboarding, question flows, and reference docs publish the exact read path. API tests are 28/28 and web/OpenClaw tests are 88/88; native parity, generated package parity, and authorized desktop/phone visual validation remain.

As a user, I can define a recurring positive habit, see due days and streaks, and record Done or Missed with optional evidence.

Where it lives

habits-index, habit, web and watch decisions.

Current evidence and next check

recurrence uses explicit fixed-home or travel-local day boundaries, rejects future or unscheduled backfill, and deduplicates concurrent receipts across web and Watch. Finish positive-habit DST and long-window weekly acceptance plus true multi-process concurrency.

As a user, I can track a negative habit using Resisted or Performed outcomes without misleading positive-habit language.

Where it lives

habits-index, habit, watch habit controls.

Current evidence and next check

web, API, iPhone relay, and Watch use Resisted/Performed copy, preserve private notes, resolve fixed-home or travel-local days, correct streaks and rewards idempotently, enforce owner scope, and retain durable receipts.

As a user, I can trust lifecycle side effects, including project completion updating unfinished linked tasks only when the contract says so.

Where it lives

Project/task services and batch update route.

Current evidence and next check

the complete status-transition matrix, exact cascaded task IDs, audit causality, idempotent retry, reward behavior, and injected mid-cascade rollback all pass.

As a user, I can assign and filter work by human or bot owner while preserving the actor that performed each change.

Where it lives

User settings, ownership fields, audit trail.

Current evidence and next check

board owner/assignee filter labels now match their behavior; complete inactive-user, reassignment, scope, and attribution checks.

As a user, I can classify and find records with reusable tags without creating duplicate or case-variant taxonomies.

Where it lives

tag, tag selectors, search.

Current evidence and next check

board search now includes tag names and descriptions; complete normalization, merge, delete, and cross-domain filter checks.

As a user, I can close work with notes, links, artifacts, git references, and a completion summary that remains inspectable.

Where it lives

Task/project detail, notes, artifacts, git ref picker.

Current evidence and next check

verify incomplete evidence, broken refs, permission changes, and read-back.

As a user, I can view provider events, Forge events, work blocks, task timeboxes, and Life Events in one readable calendar.

Where it lives

calendar-index, calendar overview.

Current evidence and next check

the phone week is a bounded seven-day swipe rail with no page overflow, and multi-day events render on every applicable day. Finish dense overlap, recurrence, and a separate month-view matrix.

As a user, I can discover, connect, configure, sync, rediscover, and remove a calendar provider without guessing provider-specific setup.

Where it lives

settings-calendar, calendar_connection specialized CRUD.

Current evidence and next check

Google polling, read-only Exchange, macOS replacement, and writable-target reuse pass the 27-test calendar suite. Finish token-expiry and provider-outage recovery.

As a user, I can define recurring work or rest windows that influence scheduling without becoming ordinary events.

Where it lives

work_block_template, calendar.

Current evidence and next check

work blocks remain distinct records, recur by local wall time across DST, support bounded ranges, exclusions, overnight windows, legacy migration, editing/deletion, and capped expansion without repeated stored rows.

As a user, I can create and edit a calendar event and understand whether it is local, mirrored, or provider-backed.

Where it lives

calendar_event, calendar guided form.

Current evidence and next check

guided local create/edit preserves wall time, duration, timezone, and all-day state; provider occurrences are explicitly read-only, and projection failures preserve the Forge record with a structured warning. Whole-series provider edits remain delegated to the provider calendar.

As a user, I can review important past, current, and future events as a linear chronology centered on now.

Where it lives

life-events-index, dedicated Life Events timeline read.

Current evidence and next check

server-side search, archive-wide past/now/future counts, bounded pages, and measured window virtualization pass; a temporary 10,000-event store returned a deep page in 93.2 ms and exact search in 83.7 ms. Cursor pagination remains open.

As a user, I can create a Life Event that lasts minutes, days, or months, including stays and festivals.

Where it lives

life_event, guided modal.

Current evidence and next check

live stay and six-day festival cards retain range copy, and calendar overlap logic covers timed and all-day multi-day spans. Finish open-ended and multi-month cases.

As a user, I can choose a well-crafted event type such as flight, train, road travel, stay, concert, cinema, date, family visit, festival, or important work, or define a custom type.

Where it lives

Life Event type catalog and custom metadata.

Current evidence and next check

flight, stay, car-trip, celebration, and custom-capable cards remain readable in the virtual timeline. Finish every catalog type, custom fallback, and migration fixture.

As a user, I can reconcile a Life Event with an existing calendar event or create the missing calendar projection without duplicates.

Where it lives

life_event, calendar_event, Life Events calendarSync.

Current evidence and next check

batch create/update/link/calendar-sync and idempotent server coverage pass. Finish fuzzy-match confirmation, provider-write failure, and unlink recovery.

As a user, I can mark an existing calendar event as a Life Event and preserve its source and calendar link.

Where it lives

Life Events fromCalendarEvent.

Current evidence and next check

the dedicated reverse-projection contract remains covered by the Life Event server suite. Finish recurring-instance, provider-edit, duplicate, and reverse-navigation fixtures.

As a user, I can attach a trusted ticket, let an enabled LLM propose travel details, review them, and create a draft without automatic file execution.

Where it lives

Artifact Store, Life Events importTicket, model settings.

Current evidence and next check

ticket import, Artifact Store trust, static scan, and human-only download tests pass without autonomous execution. Finish unreadable, malicious, duplicate, and ambiguous-ticket cases.

As a traveler, I can see origin, destination, departure, arrival, local time zones, when to leave, booking context, and current travel status.

Where it lives

Travel Life Event cards, travelStatus, map/status integrations.

Current evidence and next check

live GVA-ZRH-LAX and LAX-ZRH-GVA cards show route, booking description, duration, and correct local dates. Finish stale live-status, missing-coordinate, train, and car matrices.

As a user, I can link a Life Event to goals, Psyche records, people, notes, artifacts, and any other compatible Forge record.

Where it lives

General entity links and chronology cards.

Current evidence and next check

general link create/search coverage remains green and no artifact-specific relationship model was introduced. Finish backlinks for deleted and private targets.

As a user, I can trust that imported and displayed event times preserve the source instant, source time zone, local display zone, and date.

Where it lives

Calendar/Life Event normalization and ticket extraction.

Current evidence and next check

offset instants, IANA source zones, date-line crossings, Zurich and Los Angeles DST gaps/folds, exclusive all-day ends, en-US/de-CH display, ambiguous abbreviations, and the live Sep 12/Sep 13 return flight all pass.

As a user, I can create, edit, search, tag, date, and link Markdown notes as durable prose beside structured records.

Where it lives

notes-index, note, general links.

Current evidence and next check

the first coordinated source package passed backend 10/10, web/API 44/44, playbook 16/16, server/root, lint, format, and diff gates, but independent review found material owner-default, summary/activity visibility, direct-route ordering, cleanup-owner, anchor-deduplication, deleted/ID query-parity, and batch-response-schema gaps. The complete correction package is active; do not return this story to In review until all seven findings and adversarial regressions pass together.

As a user, I can browse and search KarpaWiki pages as durable structured-memory documents.

Where it lives

wiki-index, wiki_page specialized CRUD and search.

Current evidence and next check

test title/content search, pagination, empty state, and ranking.

As a user, I can create, read, edit, and delete a wiki page while preserving metadata, links, and history.

Where it lives

wiki-new, wiki-page-detail, wiki-edit.

Current evidence and next check

drafts persist, and edits now use one atomic revision compare-and-swap so stale clients receive a 409 before links, search data, or activity change. Finish slug-collision, backlink, and soft-delete matrices.

As a user, I can follow backlinks, citations, related pages, and general entity links from a wiki page.

Where it lives

Wiki detail, backlinks, entity relationships.

Current evidence and next check

test broken/deleted targets, link labels, permissions, and cycles.

As a user, I can ingest supported source material into KarpaWiki and inspect every job's source, mapping, status, and errors.

Where it lives

Wiki ingest modal, wiki-ingest-history, ingest APIs.

Current evidence and next check

persisted totals, loaded-match counts, terminal source errors, refresh/delete failures, URL redirect validation, DNS pinning, timeouts, content types, and byte limits pass. Finish larger batch, retry, and duplicate-source matrices.

As an operator, I can inspect wiki health, sync, reindex, and configure optional model-backed processing.

Where it lives

settings-wiki, wiki health/sync/reindex, model settings.

Current evidence and next check

no-model maintenance remains available, and reindexing is disabled unless an enabled embedding profile exists. Finish interrupted reindex, progress, and rollback.

As a user, I can explore Forge records and their relationships as a filterable Knowledge Graph.

Where it lives

knowledge-graph-index, entity graph API.

Current evidence and next check

2,000-node framing, theme repaint, and spatial arrow-key navigation pass; complete assistive-technology narration and additional dense-graph interaction checks.

As a user, I can inspect a large graph without blank frames, runaway simulation, illegible framing, or a desktop-only toolbar.

Where it lives

Graph renderer, worker/layout model, compact toolbar.

Current evidence and next check

representative 2,000-node and mobile checks pass; retain benchmark fixtures.

As a user, I can find meaningfully related local records across Forge and see the exact source evidence behind every result.

Where it lives

Local semantic index, search, Knowledge Graph, permission and provenance filters.

First evidence needed

establish a representative retrieval fixture, relevance thresholds, local resource bounds, deletion behavior, and zero cross-user leakage before choosing an embedding or index implementation.

As a user, I can browse, search, filter, and page through a large Artifact Store without loading every record or crowding the UI.

Where it lives

artifacts-index, GET /api/v1/artifacts.

Current evidence and next check

metadata-only 50-record pages, indexed full-text search, exact linked-record and state/danger/format filters, filter-aware states, and bounded UI controls pass on 10,000 mixed records; measured first/deep/search pages were 3.72/4.13/2.85 ms and the first response was 29,148 bytes.

As a trusted user or scoped trusted agent, I can add one or several supported files and see one stable upload queue.

Where it lives

Artifact guided modal, POST /api/v1/artifacts.

Current evidence and next check

the guided queue accepts up to 25 files; complete per-file progress, cancellation, retry, duplicate-byte, and partial-failure checks.

As a user, I can give each queued file a short description quickly or open a detailed guided step and return without losing other files.

Where it lives

Artifact ModalBase flow and upload queue.

Current evidence and next check

per-file descriptions and relationship drafts survive detail navigation; complete bulk-default, keyboard, and phone checks.

As a user, I can inspect precise artifact metadata: title, short and full description, source path/name, format, size, checksum, provenance, ownership, timestamps, version, links, and protection state.

Where it lives

Artifact detail/list metadata and GET/PATCH /api/v1/artifacts/:id.

Current evidence and next check

the detail view now exposes canonical file identity, source, ownership, MIME, size, original/stored checksums, storage path/key, timestamps, links, protection, structured metadata, and version facts; guided metadata edits preserve immutable evidence. Desktop and 390 x 844 live QA passed without overflow or application errors. Finish stored-row/adapter field fixtures.

As a user, I receive a static safety scan and explainable danger level before deciding whether to trust a file.

Where it lives

Artifact scan, danger score/level, findings.

Current evidence and next check

missing, completed, and failed scan states are explicit; complete malformed, macro, archive, unsupported, and scanner-failure fixtures.

As a user with an enabled LLM, I can request missing title, descriptions, provenance hints, format details, and danger interpretation, then review the proposal before applying it.

Where it lives

POST /api/v1/artifacts/:id/enrich, model settings.

Current evidence and next check

enrichment availability, completion, and failure are truthful; complete provider, prompt-injection, extraction, and precedence checks.

As an operator, I can change trust state, rescan, inspect versions and audit history, update metadata, delete, restore, and deliberately hard-delete metadata.

Where it lives

Artifact trust/scan/version/audit routes plus batch metadata actions.

Current evidence and next check

a guided trust flow requires a reason and uses the dedicated audited route while preserving scanner evidence; version/audit cards expose ordering facts, checksums, actors, timestamps, protection, and event metadata; shared soft delete remains restore-compatible. Finish stale-client, explicit restore, and deliberate hard-delete UI matrices.

As a user, I can link an artifact to any compatible entity through the general relationship model and embed its human-download anchor in notes or wiki pages.

Where it lives

POST /api/v1/artifacts/:id/links, general links, wiki renderer.

Current evidence and next check

structured general links are bounded to 100 and navigate to canonical records/graph; complete target validation, replacement, backlinks, and embeds.

As a human operator, I can download an artifact deliberately; an agent cannot autonomously download, open, execute, decrypt, or transform its bytes.

Where it lives

Human-only download/password/encrypt routes and adapter exclusions.

Current evidence and next check

human-only and disabled download states plus blocked explanations pass; complete the full actor/scope matrix and byte-integrity failures.

As a human operator, I can use supported content protection and a password hint without exposing the password to Forge agents.

Where it lives

Human encryption/download flow and protected metadata.

Current evidence and next check

password/encryption flows remain human-only and explicit; complete transition, wrong-password, hint, version, and secret-log checks.

As a user, I can create, search, edit, link, archive, and restore a Person without turning that person into a Forge user or peer identity.

Where it lives

people-index, person, shared batch CRUD, general entity links.

Current evidence and next check

Person identity, aliases, contacts, facts, dates, notes, ownership, optimistic versions, soft deletion, restoration, and links use the shared entity contract and remain separate from peer keys, grants, and devices.

As a user, I can browse a large People collection and open one person's local details, current context, shared information, devices, and security history without loading every record.

Where it lives

People collection/detail workspace, GET /api/v1/people, Person context read model.

Current evidence and next check

signed revision-bound cursors, bounded sections, deliberate retry, 10,000-person virtualization, desktop and phone layouts, and field-level redaction pass; the full release gate remains.

As a user, I can add or edit a Person through a guided modal that asks only for the relationship context and missing details that matter.

Where it lives

People ModalBase flows and Person batch mutations.

Current evidence and next check

create/edit flows preserve drafts, optional details, general links, focus, keyboard behavior, and sensitive-field review. Complete publication evidence is pending with the aggregate release.

As a user with existing People pages in KarpaWiki, I can review candidates and explicitly associate, create, or skip each one without destructive conversion or guessed matches.

Where it lives

Wiki candidate scan, preview/apply actions, profile_page entity links.

Current evidence and next check

bounded candidate paging, ambiguity handling, version-bound preview, atomic idempotent apply, and existing-page preservation pass focused tests.

As a user, I can pair two independently operated Forge installations by scanning a short-lived QR invitation and confirming the same peer identity before either side shares data.

Where it lives

People pairing flow, iPhone scanner, peer invitation and confirmation routes.

Current evidence and next check

one-use invitations, signed transcript/state/evidence binding, explicit verification, replay handling, rollback, expiration, and owner isolation pass across Node, Rust, web, and native tests.

As a user, I can inspect and manage peer relationships and approved devices without confusing a local Person, remote principal, device certificate, or companion credential.

Where it lives

People relationship/device/security views, peer identity and revocation routes.

Current evidence and next check

certified device identity, rotation, revocation, companion v2 enrollment, current-user presence, recovery boundaries, and multi-owner routing are fail-closed and audited.

As a user, I can propose, counter, review, accept, and revoke directional sharing rules that state which projection, fields, precision, time span, cache policy, and approved devices apply.

Where it lives

Sharing preview and grant flows, signed grant versions, projection registry.

Current evidence and next check

grants require human review and both parties' verified signatures; broad sharing excludes protected domains; counterproposals cannot silently widen access; current-device approval and revocation are enforced before projection delivery.

As a user, I can ask bounded questions such as another person's calendar availability, current goal horizon, or cycling aggregate and receive only information that person allowed to be shared.

Where it lives

Person question interpret/execute/history routes, registered peer projections.

Current evidence and next check

relative dates, time zones, interpretation hashes, schema validation, grant intersection, source preference, result limits, audit, and the initial Rust query round trips pass. Arbitrary prompts, SQL, raw samples, and generic peer HTTP are not exposed.

As a user, I can tell whether shared information is local or remote, fresh, stale, incomplete, revoked, offline, or waiting for resynchronization.

Where it lives

Remote projection cache, freshness UI, query history, revocation and resync actions.

Current evidence and next check

authenticated encrypted caches, expiry, key loss, device attribution, withdrawal, quarantine, stale display, bounded retry, and explicit resync states pass focused tests.

As a self-hosting user, I can communicate directly when peers overlap online and optionally use a replaceable mailbox or relay without depending on a Forge-operated account service.

Where it lives

Forge Peer daemon, Iroh, Tor, transport abstraction, reference connectivity service.

Current evidence and next check

transport-independent encrypted envelopes, OpenMLS state, durable outbox/inbox delivery, direct Iroh, Tor, optional mailbox, restart recovery, and provider trust boundaries pass integration tests. The reference service remains optional and replaceable.

As a trusted agent, I can use scoped People reads and typed questions while pairing, device, grant, presence, download, and other human decisions remain unavailable to agent tools.

Where it lives

OpenAPI, onboarding, OpenClaw, Hermes, Codex MCP, Forge Memory.

Current evidence and next check

source and packaged tool allowlists, scopes, strict schemas, human-only exclusions, and conversational People guidance are byte-aligned across adapters.

As an iPhone or Watch user, I can review People context, scan pairing material, approve protected actions with deliberate presence, and choose which People appear on Watch without exposing private fields.

Where it lives

iPhone companion, Watch People selection, Entity Navigation pins, companion v2 routes.

Current evidence and next check

native enrollment, Secure Enclave request signing, pairing, protected approvals, retry, accessible pin/unpin confirmation, bounded Watch selection, and source freshness have focused unit/UI evidence; final signed archive and TestFlight publication remain release gates.

As a user, I can create a preference catalog that defines one decision domain and its provenance.

Where it lives

preferences-index, preference_catalog.

Current evidence and next check

guided catalog creation now covers purpose and boundaries, one owner/domain, stamped provenance, normalized duplicates, generic links, bounded lists, retry-safe create, concurrent uniqueness, reversible archive/restore, and direct/batch authorization. Link writes validate target read access without distinguishing missing from inaccessible. Source tests pass; browser visual QA and held contract generation remain.

As a user, I can maintain reusable catalog concepts and concrete preference items without confusing the two.

Where it lives

preference_catalog_item, preference_item.

Current evidence and next check

linked concepts now have one atomic identity with deterministic duplicate repair and evidence remapping, while direct same-label records remain distinct and receive a non-blocking warning. Finish membership and deletion-effect matrices.

As a user, I can describe the context in which a preference applies and merge contexts without losing evidence.

Where it lives

preference_context, Preferences merge action.

Current evidence and next check

ordinary context definition uses shared batch CRUD; live onboarding and every adapter now require both contexts to be read before forge_merge_preferences_contexts, with one sourceContextId and one targetContextId, an explained evidence move/source deactivation/target recomputation, and explicit merge intent. OpenAPI publishes the same request body. Complete overlap, redirect, and failure-rollback matrices.

As a user, I can compare two items and record a pairwise judgment with strength and context.

Where it lives

preference_judgment action route.

Current evidence and next check

card, button, and keyboard submissions share an immediate per-pair lock that remains active through the mutation, preventing duplicate judgments under mixed rapid input. Complete pair validity, ties, undo, failure retry, and server idempotency matrices.

As a user, I can mark a direct signal such as favorite or veto and understand how it affects the model.

Where it lives

preference_signal action route.

Current evidence and next check

any selected item now opens the guided dialog with current mark, owner/domain/context, provenance, replacement, conflicts, and exact model effect. Writes return recomputed score and effectiveSignal; neutral preserves history but adds no direct weight, evidence, or confidence. Backend, web, OpenAPI, bounded-history, concurrency, and agent tests pass; browser visual QA and held contract generation remain.

As a user, I can inspect inferred scores and their supporting judgments/signals instead of receiving an unexplained ranking.

Where it lives

Preferences workspace/read model.

Current evidence and next check

live onboarding and all adapter playbooks now define an evidence-first read flow through GET /api/v1/preferences/workspace, explain judgments, signals, overrides, evidence count, and uncertainty before offering a dedicated follow-up action. Complete sparse/conflicting evidence, recalculation, and UI explanation matrices.

As a user, I can add an existing Forge entity to a preference workspace without duplicating its identity.

Where it lives

Preferences enqueue-from-entity action and general links.

Current evidence and next check

enqueue now uses a partial unique linked-identity index and atomic upsert, including deterministic repair of legacy duplicates. Finish unsupported/deleted source and backlink checks.

As a user, I can compare selected records across time without exporting them or losing their type, source, units, and provenance.

Where it lives

Preferences, insights, Health, Psyche, Knowledge, comparison read model.

First evidence needed

validate common comparison tasks and define type-safe alignment, unit, missing-data, permission, and provenance contracts.

As a user, I can enter Psyche and understand the available reflective records and recent context.

Where it lives

psyche-index.

Current evidence and next check

verify first-use guidance, privacy, return paths, and dense-state navigation.

As a user, I can articulate a value as a lived direction and connect it to actions, goals, beliefs, and reports.

Where it lives

psyche-values, psyche_value.

Current evidence and next check

the guided flow preserves rough/conflicted user wording, reveals the lived-direction question only after a value is named, blocks only missing required meaning, moves optional ownership/links later, and preserves typed action wording while dropping blank lines on save. Complete already-clear, competing-value, edit, correction, and relationship simulations.

As a user, I can map a behavior pattern through cue/context, visible response, short-term payoff, long-term cost, and preferred alternative.

Where it lives

psyche-patterns, behavior_pattern.

Current evidence and next check

the five-step guided flow progressively separates concrete cue, observable response, immediate protective function, later cost, and preferred alternative with non-blaming blockers; optional ownership and links come last. Complete already-clear, mixed-function, edit, and correction simulations.

As a user, I can record one observable behavior or urge as away, committed, or recovery behavior and link its evidence.

Where it lives

psyche-behaviors, behavior.

Current evidence and next check

the five-step guided flow distinguishes observable action from belief, pattern, goal, and trigger report; preserves authored wording during edits; progressively asks for cues, urge, immediate function, later cost, or repair action by behavior kind; and moves optional ownership to final links. Complete committed-action edge cases, correction/withdrawal, linked evidence, and live edit matrices.

As a user, I can name a belief in my own words, estimate confidence, examine evidence, connect an optional schema, and propose a more flexible alternative.

Where it lives

psyche-schemas-beliefs, belief_entry.

Current evidence and next check

the guided flow preserves exact user wording, distinguishes experiences and interpretations from facts, welcomes contradictory evidence, frames alternatives tentatively, and requires renewed consent whenever the formulation changes. Complete schema-link, update, withdrawal, and ambiguous-evidence simulations.

As a user, I can describe a recurring mode with cues, needs, fears, burdens, protective function, risks, and preferred responses.

Where it lives

psyche-modes, mode_profile.

Current evidence and next check

mode creation now requires a tentative recognizable name and a correctable protective-function hypothesis, explicitly avoids diagnostic certainty, keeps legacy sparse profiles editable, and moves optional ownership to final links. Complete explicit needs/risks/preferred-response fields, episode links, family correction, and live edit matrices.

As a user, I can complete a guided mode session that helps name the active part and choose a next response without prematurely creating a durable profile.

Where it lives

psyche-mode-guide, mode_guide_session.

Current evidence and next check

the one-question flow develops functional hypotheses and a next response without premature profile creation; complete resume and candidate ambiguity checks.

As a user, I can create and retrieve a concise therapeutic flashcard for a trigger, urge, value pivot, or recovery move.

Where it lives

psyche-flashcards, flashcard.

Current evidence and next check

test text fit, images, retrieval cues, links, and phone/watch presentation.

As a user, I can maintain reusable event and emotion vocabularies for reports without losing the option to use my own words.

Where it lives

psyche-reports, event_type, emotion_definition, shared batch CRUD.

Current evidence and next check

owner-scoped custom entries, immutable built-ins, normalized duplicate checks, retry-safe create, exact API contracts, and guided ModalBase management are complete. Reports retain their own event and emotion words across preset changes, renames, restoration, and hard deletion. Canonical Psyche scope includes both vocabularies and mode_guide_session. Source gates are green; generated copies are held and browser QA is pending by instruction.

As a user, I can build a trigger report for one episode across situation, emotions, thoughts, body cues, behaviors, consequences, modes, schemas, and next moves.

Where it lives

psyche-reports, trigger_report.

Current evidence and next check

the complete source package now covers progressive guided intake, incomplete-memory defaults, interpretation consent and correction, owner-scoped deep search, stable keyset pagination, idempotent retry, revision conflict recovery, all five planning links, reversible deletion, generic-link hard deletion, Watch defaults, and aligned agent playbooks. Independent source review found no remaining defect; packaged migration 092, runtime, and OpenAPI parity remain held behind the People integration gate.

As a user, I can inspect one trigger report as a coherent chain and follow every linked record.

Where it lives

psyche-report-detail.

Current evidence and next check

verify chronology, missing links, corrections, and mobile readability.

As a user, I can create a reusable questionnaire with provenance, sections, questions, scoring rules, and instructions.

Where it lives

psyche-questionnaires, psyche-questionnaire-new, questionnaire_instrument.

Current evidence and next check

test validation, drafts, long forms, and imported instruments.

As a user, I can inspect, edit, clone, version, and publish a questionnaire without changing historical runs.

Where it lives

psyche-questionnaire-detail, psyche-questionnaire-edit.

Current evidence and next check

verify version boundaries, scoring changes, and concurrent edits.

As a user, I can answer a questionnaire one prompt at a time, pause safely, and complete it once.

Where it lives

psyche-questionnaire-run, questionnaire_run actions.

Current evidence and next check

test required/optional answers, resume, progress, offline failure, and idempotency.

As a user, I can review a completed run's raw answers, computed scores, context, and instrument version.

Where it lives

psyche-questionnaire-run-detail.

Current evidence and next check

verify scoring provenance, missing answers, version labels, and export.

As a user, I can log and review dated observations about emotions, thoughts, triggers, body state, movement, and context.

Where it lives

psyche-self-observation, note-backed self_observation.

Current evidence and next check

verify calendar boundaries, note linkage, movement entries, and privacy.

As a user, I can inspect device-use patterns beside mood, attention, and routines.

Where it lives

psyche-screen-time, companion Screen Time sync.

Current evidence and next check

test permissions, no-data, partial categories, time zones, and stale sync.

As a user, I can review Psyche metrics such as mood, urges, self-regulation, and conversation-derived signals with clear provenance.

Where it lives

psyche-metrics.

Current evidence and next check

verify metric definitions, missingness, confidence, filters, and source links.

As a user, I can see how values, goals, behaviors, beliefs, modes, and reports relate without mistaking correlation for causation.

Where it lives

psyche-goal-map.

Current evidence and next check

verify graph semantics, explanations, large graphs, and accessibility.

As a user speaking naturally to an agent, I receive calm reflection, one well-sequenced question at a time, and useful hypotheses offered for discussion.

Where it lives

Onboarding questionFlow, plugin playbooks, MCP tools.

Current evidence and next check

mode-guide reflections are tentative, functional, and non-diagnostic; complete the per-entity simulated Psyche matrix.

As a user, I can correct, decline, defer, or keep an agent's interpretation before any sensitive record is written.

Where it lives

Agent readiness checks and mutation confirmation.

Current evidence and next check

correction, uncertainty, decline, and defer precede writes, and defer is mutation-free; complete refusal, crisis, and persistence checks.

As a user, I can inspect sleep sessions, stages, recovery context, annotations, and trends by wake date.

Where it lives

sleep-index, sleep_overview, sleep_session.

Current evidence and next check

the live mobile flow exposes wake-date freshness, calendar trends, normalized stages, source records, and raw provider evidence without overflow; finish overlapping-source, nap, DST, and manual-edit fixtures.

As a user, I can review workouts with type, timing, distance/energy, route, effort, meaning, and linked evidence.

Where it lives

sports-index, sports_overview, workout_session.

Current evidence and next check

the 1,158-session history, habit reconciliation, filters, bounded summaries, full-by-id reads, and selected-user authorization pass; finish the remaining long-route and mixed-source detail matrix.

As a user, I can inspect one workout's heart-rate timeline, zones, route points, events, and preserved raw evidence.

Where it lives

sports-workout-detail.

Current evidence and next check

adaptive detail now bounds dense heart-rate/route evidence while preserving endpoint samples, and missing-sensor sessions remain explicit instead of zero-filled. Finish map-theme, privacy presentation, and live large-timeline interaction checks.

As a user, I can understand acute/chronic load, intensity mix, zone time, VO2max context, targets, and next-workout guidance.

Where it lives

training-load-index, read-only training_load.

Current evidence and next check

the full explanation model and compact 2-column phone summary pass live and automated checks; one bulk analytics read reduced the measured route median from 191.6 ms to 145.0 ms. Finish stale-baseline and mixed-sport fixtures.

As a user, I can review daily HealthKit vitals, recovery markers, cardio fitness, and trends with units and source quality.

Where it lives

vitals-index.

Current evidence and next check

the complete 20,288 px live phone route remains readable, themed, and overflow-free with source-quality detail; finish unit-conversion, duplicate-source, outlier, and boundary fixtures.

As a user, I can compare sports by time, share, sessions, calories, energy rate, and heart-rate-backed load density without mistaking missing evidence for zero.

Where it lives

sports-index, GET /api/v1/health/fitness.

Current evidence and next check

all-time, 12-month, and 90-day aggregates expose per-metric coverage, exclude future plans, use readable compact chart labels with full tooltips, and stay readable across a 19-sport history on phone and desktop.

As a user with a large workout history, I can search exercise types from a visible keyboard-accessible autocomplete and scroll a bounded session browser without loading every row into the DOM.

Where it lives

sports-index, sessionDetail=summary&analysisDetail=compact, workout detail read.

Current evidence and next check

the real 1,158-session store mounts only 8-12 history rows at the first and final sessions, the portal autocomplete remains visible and keyboard accessible, and the browser contract transfers 33.7% fewer bytes than the prior summary response while preserving full-by-id reads.

As a user, I can log food quickly, search or create reusable foods, and preserve serving, nutrient, source, and confidence details.

Where it lives

weight-loss-index, dedicated nutrition actions.

Current evidence and next check

custom, search, ChatGPT, quantity conversion, edit, history, selected-day, selected-user, and committed-response-loss retry flows pass; stable idempotency keys prevent duplicate writes. Finish duplicate-catalog and fully offline queue cases.

As a user, I can compare intake with activity-aware calorie targets and see whether the evidence is reliable enough to guide a decision.

Where it lives

Read-only weight_loss overview.

Current evidence and next check

live target, active-energy branch, remaining-calorie, historical balance, source confidence, and explicit arithmetic remain separate and readable; finish sparse-activity and unit-preference fixtures.

As a user, I can track weight, body composition, appearance, energy, cravings, gut comfort, and sport fueling without collapsing them into one score.

Where it lives

Weight Loss subviews and dedicated check-ins.

Current evidence and next check

body, appearance, subjective, gut, food-quality, training-fuel, and data-quality signals remain distinct, enforce one selected owner, reject cross-owner food links, and retry idempotently. Finish missing-metric and sensitive-copy matrices.

As a user, I can define and review an N-of-1 nutrition or body experiment with hypothesis, exposure, outcomes, confounders, and uncertainty.

Where it lives

Weight Loss experiments.

Current evidence and next check

the API now preserves hypothesis, intervention, primary metric, dates, success criteria, confounders, status, and conclusion across OpenAPI, MCP, OpenClaw, Hermes, and web. A three-step guided modal works at phone and desktop sizes. Finish adherence, overlap, minimum-evidence, and conclusion-review flows.

As a user, I can review movement by day, month, all time, and arbitrary timeline range without treating mobility records as generic CRUD.

Where it lives

movement-index, dedicated movement reads.

Current evidence and next check

all four dedicated views remain available; the initial Life view now issues one bounded timeline read instead of two, avoiding one roughly 271 KB transfer. Finish empty and 10,000-box benchmarks.

As a user, I can inspect stays, trips, gaps, and known places with clear source and confidence.

Where it lives

Movement timeline, places, box/trip detail.

Current evidence and next check

timeline detail remains explicit, the data-only invalid-box read is lazy, and 29 live places default to eight plus an intentional expansion. Finish low-confidence, hidden-location, and timezone fixtures.

As a user, I can select a period or places and receive bounded aggregate time and travel summaries.

Where it lives

Movement selection.

Current evidence and next check

selection remains on the dedicated aggregate route and its phone metrics now use a dense two-column layout. Finish inclusive-bound, alias, long-range, and unit matrices.

As a user, I can create or correct a place and preview whether a manual stay/trip repair would conflict before applying it.

Where it lives

Movement settings/place/user-box/preflight routes.

Current evidence and next check

place and preflight flows remain dedicated; place repair now carries selected-user scope and refuses a different owner's record. Finish radius, overlap, and duplicate-place cases.

As a user, I can update or delete a manual movement box, invalidate a wrong automatic box, and correct stay, trip, or route points with an audit trail.

Where it lives

Movement repair action routes.

Current evidence and next check

place, stay, trip, point, detail, and user-box repair routes enforce selected-user ownership and document it in OpenAPI. Finish downstream aggregate, retry, and undo/recovery cases.

As a user, I can see today's Action Point capacity, expected energy curve, drains, fatigue signals, recovery, and remaining capacity.

Where it lives

life-force-index, GET /api/v1/life-force.

Current evidence and next check

the complete live workspace is 19% shorter on phone while retaining capacity, curve, drains, warnings, recovery, and stats; finish first-use, overloaded-day, and stale-profile fixtures.

As a user, I can update my Life Force profile without replacing the dedicated energy model with generic entity fields.

Where it lives

Life Force profile.

Current evidence and next check

dedicated partial-profile mutation and recalculation pass the full server route suite; finish ownership and every bound edge.

As a user, I can define weekday energy templates that reflect recurring capacity patterns.

Where it lives

Life Force weekdayTemplate.

Current evidence and next check

guided curve editing and dedicated weekday writes pass focused UI and full server tests; finish all-weekday, time-zone, and reset cases.

As a user, I can record a fatigue signal with intensity and context and see its effect on the current model.

Where it lives

Life Force fatigueSignal.

Current evidence and next check

the guided fatigue signal reaches the dedicated route and updates the workspace in focused tests; finish expiry, correction, repeated-signal, and future-time cases.

As a user, I can browse and search a bounded catalog of graph flows and reusable node boxes.

Where it lives

workbench, Workbench flow/box catalog reads.

Current evidence and next check

the complete source package now uses bounded SQL-backed summary pages, server search and facets, enabled/disabled endpoint state, lazy active-tab loading, URL-restored filters, incremental paging, retry-preserved results, full typed box disclosure, read-only catalog GETs, and aligned source OpenAPI/agent guidance. Large 600-flow and focused web/tool tests pass; generated tool documentation parity and authorized desktop/phone visual validation remain.

As a user, I can create, inspect, update, and delete a flow with stable input/output contracts.

Where it lives

workbench-flow, Workbench flow CRUD.

Current evidence and next check

guided creation and exact-title deletion confirmation pass; complete version, restore, and concurrent-update checks.

As a user, I can edit nodes and edges with understandable contracts, valid connections, undo, and no accidental graph loss.

Where it lives

Workbench graph editor.

Current evidence and next check

graph editing remains available when model settings are unavailable; complete cycles, ports, keyboard, conflict, and large-graph checks.

As a user or trusted agent, I can execute a saved or one-off flow and see truthful progress and failure state.

Where it lives

Workbench runFlow and runByPayload.

Current evidence and next check

duplicate run/chat submissions are blocked while pending; complete cancellation, timeout, partial failure, retry, and idempotency.

As a user, I can inspect run history, one run, its node list, and a node result without loading unbounded execution data.

Where it lives

Workbench run history/detail/node reads.

Current evidence and next check

paged summaries retain bounded primary output compatibility while excluding full traces, and exact run/node reads remain separate. Finish the redaction, missing-node, and old-version matrix.

As a user, I can retrieve the stable published output and latest output for one node separately from raw run traces.

Where it lives

Workbench published/latest output reads.

Current evidence and next check

published and latest output compatibility remains stable with bounded run summaries and durable run evidence. Finish no-publish, stale-publish, failed-latest, and content-type cases.

As a user, I can continue a saved flow through a chat follow-up while preserving the flow and run context used.

Where it lives

Workbench chatFlow.

Current evidence and next check

mock chat preserves conversation continuity, validates required inputs, and persists bounded run evidence. Finish no-model, long-context, retry, and attribution cases.

As a learner, I can browse installed courses, inspect a syllabus and progress, and continue the correct lesson without reconstructing internal ids.

Where it lives

courses-index, course-detail, course-learn.

Current evidence and next check

package-backed catalog, exact detail, progress, and learner-safe sessions are implemented; complete empty, multi-user, and resume-state checks.

As a learner, I can submit one activity answer and receive truthful feedback, including an explicit withheld result when structured grading is unavailable.

Where it lives

course-learn, dedicated attempt action.

Current evidence and next check

deterministic multiple-choice and model-backed written assessment preserve attempts and mastery evidence; complete retry, unavailable-model, and adversarial-answer checks.

As a user, I can find due concepts and inspect definition, prerequisites, cross-course evidence, and multidimensional mastery without treating a score as a verdict.

Where it lives

concepts-index, concept-detail.

Current evidence and next check

first-class concept reads and evidence-backed mastery are implemented; complete due-ordering, sparse-evidence, and cross-course checks.

As an authorized operator, I can import a validated portable course package or export its canonical package without bypassing integrity and learner-evidence protections.

Where it lives

Course package import/export.

Current evidence and next check

canonical hash, reference validation, concept-conflict checks, and evidence-protected replacement are implemented; complete large-package, provenance, and transfer-boundary checks.

As an agent, I can bootstrap against live Forge onboarding and learn the exact entity catalog, fields, question flows, scopes, and route families.

Where it lives

/api/v1/agents/onboarding, OpenAPI, adapter bootstrap.

Current evidence and next check

OpenClaw, Hermes, and Codex now require a live-onboarding handshake and treat its 47-entry catalog and specialized route maps as authoritative; contract tests reject missing playbooks, adapter drift, invalid issue/subtask entity types, and route-family guessing. Finish generated-doc and installed-runtime parity fixtures.

As a user, I can ask an agent to add or update a record through natural conversation that gathers only missing or unclear information.

Where it lives

Entity question flows and plugin playbooks.

Current evidence and next check

all adapters now compute a missing-information diff, skip optional/default polish, read before narrow updates, preserve omitted fields, and act when no blocking ambiguity remains. Finish create/update/review/navigation simulations for every catalog entry.

As a user in Psyche, I receive therapist-like active listening and discussable hypotheses; in other domains I receive concise, structured guidance.

Where it lives

Psyche coaching playbooks and general entity playbooks.

Current evidence and next check

shared Psyche playbooks now retain the concrete episode and accepted/rejected wording, reflect specifics, offer one grounded hypothesis after a visible function, accept correction without defending it, and stop after consent. Finish scored simulations across every Psyche entity and difficult/distressed cases.

As an agent, I use batch CRUD for ordinary stored entities, action routes for workflows, and dedicated families for specialized domains without route guessing.

Where it lives

Onboarding route model, OpenAPI, MCP/plugin tools.

Current evidence and next check

Hermes now publishes dedicated Workbench paths and exact fields; complete negative tests across every route family and adapter.

As an operator, I can issue scoped tokens or use a trusted local/Tailscale operator session, see live agent sessions, rotate credentials, and revoke access.

Where it lives

Agent settings, token/session APIs.

Current evidence and next check

review-first tokens are now genuinely read-only, mutation scopes are stripped at submission, and model credential tests require an operator session. Finish bootstrap-budget, heartbeat, reconnect, rotation, and revocation matrices.

As an operator, I can install Forge Memory and connect OpenClaw, Hermes, Codex MCP, and Claude Code MCP to the same runtime.

Where it lives

forge-memory, OpenClaw, Hermes, Codex, Claude adapters.

Current evidence and next check

Forge Memory doctor now verifies the data root is a readable/writable directory without modifying existing contents, preservation markers survive doctor/update/uninstall smoke, and Hermes packages both conversation playbooks. Finish clean-host and current released OpenClaw/Hermes/Codex/Claude install matrix.

As a user, I can trust agent writes because the adapter reads back affected records and reports partial failure, generated IDs, and side effects.

Where it lives

Batch/action tools, operation results, verification paths.

Current evidence and next check

Hermes mutations report verification, partial failure, and unavailable read-back; complete mixed, conflict, stale-ID, and normalized-field checks.

As an operator, I can distinguish human and bot identity, ownership, source, session, and trust for every sensitive mutation.

Where it lives

User/agent settings, audit trail, auth headers.

Current evidence and next check

authorization matrix across artifacts, Psyche, movement repairs, and settings.

As an operator, I can find runtime, data, user, calendar, mobile, model, agent, reward, wiki, log, and bin settings from one coherent index.

Where it lives

settings-index.

Current evidence and next check

verify names, descriptions, permissions, mobile layout, and return paths.

As an operator, I can identify the active data root, create a backup, export data, and inspect recovery state without risking live data.

Where it lives

settings-data, Forge Memory export/doctor.

Current evidence and next check

backup archives/manifests use owner-only permissions, disclose credential-bearing sensitivity, publish atomically with the manifest last, and clean partial failures. Finish checksum, restore-drill, and disk-full matrices.

As an operator, I can review soft-deleted records and restore them before any deliberate permanent cleanup.

Where it lives

settings-bin, batch restore/hard-delete.

Current evidence and next check

Bin rendering and batches are capped at 40, permanent delete is confirmed, and mutation failures remain visible; complete entity and authorization matrices.

As an operator, I can inspect bounded diagnostic logs and errors with enough context to recover without exposing secrets.

Where it lives

settings-logs.

Current evidence and next check

diagnostics use bounded API filters, local OR filters, retryable older pages, and focus-stable search; complete download, retention, and redaction matrices.

As an operator, I can manage human and bot users, relationships, ownership defaults, and visibility.

Where it lives

settings-users.

Current evidence and next check

verify inactive users, duplicate identity, transfer, relationship direction, and scope.

As an operator, I can configure available local or remote model providers, defaults, reasoning settings, and health checks.

Where it lives

settings-models.

Current evidence and next check

stored credentials are bound to their saved provider, base URL, and model; caller overrides require a fresh key, and health checks require an operator session. Finish missing-key, invalid-model, local-offline, and fallback matrices.

As an operator, I can inspect and repair iPhone/watch pairing and sync from the web app.

Where it lives

settings-mobile, settings-mobile-lab.

Current evidence and next check

ready/unavailable transports, expired codes, source reconciliation, bulk revoke, ambiguous response guidance, and atomic replacement rollback pass. Finish wrong-runtime, reused-code, reconnect, movement, and phone-sized matrices.

As a user, I earn XP and streak progress from truthful Forge activity and can understand the current progression state.

Where it lives

Overview, rewards APIs, settings-rewards.

Current evidence and next check

the complete package now covers owner-scoped payload idempotency, atomic ledger writes, bounded incremental reconciliation, canonical local-day rules, authorized asset installation, durable imagery, and acknowledgement-safe accessible celebrations. Focused API, migration, web, asset, typecheck, build, formatting, and live-health gates pass; independent post-implementation adversarial validation remains.

As a user, I can browse earned and locked trophies in a bounded Trophy Hall with visible real artwork.

Where it lives

rewards, gamification asset API.

Current evidence and next check

first-viewport featured shelf, locked fallback, bounded catalogs, and direct sprite serving are covered.

As a user, I can see Smith's current state, equipment, and progression imagery without broken or disappearing assets.

Where it lives

Overview Smith widget, Trophy Hall, armory assets.

Current evidence and next check

current overview and Trophy Hall paths pass; extend all theme/offline/fallback combinations.

As a user who prefers reduced motion, I retain the information and visual state without forced decorative animation.

Where it lives

Shell, signal deck, reward celebrations.

Current evidence and next check

reduced-motion rewards use zero-duration visual receipts, live announcements, safe timers, and manual dismissal; complete runtime preference-change checks.

As a user, I can pair the iPhone by QR and understand which runtime and transport I am authorizing.

Where it lives

Companion pairing, settings-mobile, Forge Memory pair-ios.

Current evidence and next check

fresh and expired code guidance, explicit Iroh/manual transport state, one-time payload copy, long-lived verification, revoke, and atomic replacement pass. Finish reused, wrong-runtime, and revoked-payload device checks.

As a user, I can connect over secure Tailscale/HTTPS or Forge's Iroh path, with manual HTTP only as an explicit choice.

Where it lives

URLSession, Rust Iroh bridge, discovery.

Current evidence and next check

test route separation, fallback, relay, timeout, captive network, and reconnection.

As a user, my pairing credentials remain in Keychain and are not exposed in logs, screenshots, or shared defaults.

Where it lives

iOS credential store and diagnostics.

Current evidence and next check

current and legacy diagnostics redact credentials during logging, decode, copy, and export; complete migration, reinstall, lock, and rotation checks.

As a user, I can grant or deny HealthKit, location, Screen Time, and background permissions individually and see what each enables.

Where it lives

Native permission onboarding and settings.

Current evidence and next check

test partial denial, later enablement, revocation, and explanatory copy.

As a user, I can import sleep, workouts, recovery, and vitals without duplicates and see backend acceptance/progress.

Where it lives

HealthKit sync and health APIs.

Current evidence and next check

test incremental anchors, overlapping sources, large history, retry, and date zones.

As a user with a large workout history, I can upload compressed, resumable chunks and continue after interruption without replaying accepted data.

Where it lives

Mobile upload session/chunk/progress APIs.

Current evidence and next check

benchmark large archives; test raw/zlib formats, resume, corruption, and partial ingest.

As a user, I can publish movement evidence with clear permission, retention, draft/review, and repair behavior.

Where it lives

CoreLocation, Movement sync, dedicated Movement API.

Current evidence and next check

test background gaps, low-power mode, privacy modes, travel, and duplicates.

As a user, I can sync Screen Time observations into Psyche only after the required Apple authorization.

Where it lives

Screen Time report extension and self-observation.

Current evidence and next check

test extension availability, denied access, category changes, and stale reports.

As a user, foreground and background sync are idempotent, resumable, observable, and battery-conscious.

Where it lives

BackgroundTasks, sync queue, backend receipts.

Current evidence and next check

measure battery/network behavior and test kill/relaunch, offline, and race conditions.

As a user, I can open the full Forge web experience in the companion and use native sync/settings controls without the two layers fighting for space.

Where it lives

Embedded web app and floating native control center.

Current evidence and next check

test safe areas, keyboard, rotation, theme, navigation, and offline behavior.

As a user or support operator, I can inspect pairing, transport, permission, freshness, and sync diagnostics and take a valid recovery action.

Where it lives

Native settings/diagnostics and web mobile settings.

Current evidence and next check

support diagnostics now redact current and legacy credential formats; complete each failure, recovery, and export scenario.

As an iPhone user, I can install the public companion through a normal distribution channel after its sync, permission, privacy, and recovery contracts are verified.

Where it lives

App Store distribution, release metadata, iPhone verification gates.

First evidence needed

require the applicable IOS-01 through IOS-11 gates, privacy disclosures, support path, signed build evidence, and external store approval before public availability.

As a watch user, I receive a compact, fresh Forge snapshot whose age and source are visible.

Where it lives

Watch snapshot API and WatchConnectivity.

Current evidence and next check

snapshot age, stale, clock-skew, unavailable, and source states are explicit; complete payload-size and offline-transition checks.

As a watch user, commands use a secure direct HTTPS route first and the paired iPhone relay only when direct access is unavailable.

Where it lives

Direct watch transport and phone relay.

Current evidence and next check

direct/phone batches are bounded and continue after receipts; complete route-loss, handoff, duplicate, and recovery checks.

As a watch user, every outgoing command is stored durably and only appears complete after a Forge receipt.

Where it lives

Watch outbox and /mobile/watch/actions:batch.

Current evidence and next check

durable bounded outboxes clear only after receipts and preserve dedup history; complete crash, conflict, rejection, and queue-pressure checks.

As a watch user, I can review Now and the current actionable context without opening the phone.

Where it lives

Watch Now surface.

Current evidence and next check

stale, clock-skewed, and unavailable snapshots now lead with precise source/age guidance and a Refresh now action while cached Now/run cards remain swipe-accessible; fresh snapshots retain the original layout. Complete no-work, active-run, due-habit, attention, and offline-transition matrices.

As a watch user, I can start, heartbeat, complete, release, or move work with explicit receipts.

Where it lives

Watch Work surface and task_run actions.

Current evidence and next check

command receipts persist and deduplicate; complete competing-run, timeout, offline, and accidental-tap scenarios.

As a watch user, I can record positive and negative habit outcomes with clear Done/Missed and Resisted/Performed language.

Where it lives

Watch Habits surface, streak rings, habit.

Current evidence and next check

habit outcomes retain durable deduplicated receipts; complete day-boundary, correction, offline, and long-label checks.

As a watch user, I can inspect compact Goals and Today summaries without pretending the watch is a full planning editor.

Where it lives

Watch Goals and Today surfaces.

Current evidence and next check

test ordering, empty state, truncation, and deep link to phone.

As a watch user, I can inspect compact Health and Movement freshness and useful current signals.

Where it lives

Watch Health and Movement surfaces.

Current evidence and next check

test permission denial, stale sync, missing metrics, and privacy.

As a watch user, I can review Psyche prompts and Attention items and take only safe, bounded actions.

Where it lives

Watch Psyche and Inbox surfaces.

Current evidence and next check

verify sensitive-copy quality, privacy, snooze/dismiss eligibility, and handoff.

As a watch user, I can inspect and trigger Sync with truthful direct/relay/offline status.

Where it lives

Watch Sync surface.

Current evidence and next check

Sync shows snapshot source, freshness, pending count, and latest receipt; complete transport, retry, and stale-receipt checks.

As a watch user, I can quickly capture an emotion, trigger, routine, prompt, place, trip, workout, or note and review the backend receipt.

Where it lives

Watch quick capture and action envelopes.

Current evidence and next check

quick captures use bounded durable envelopes and visible latest receipts; complete every capture, dictation, ambiguity, and correction scenario.

As a watch user, I can launch Habits, Check In, Mark Moment, and Emotion from widgets or App Intents.

Where it lives

WidgetKit and App Intents.

Current evidence and next check

test locked phone, stale widget, intent failure, localization, and deep links.

As a new user, I can choose the outcome I want from Forge and receive a short first-run path that ends in a useful result rather than a tour of every screen.

Where it lives

First-run experience, starter data, permissions, progress and resume state.

First evidence needed

test the top three intended outcomes with new users and define skip, resume, empty, offline, and permission-denied behavior without mutating existing accounts.

As a prospective user, I can try a safe public demonstration of Forge without installing it or exposing personal information.

Where it lives

Isolated demo runtime, deterministic sample data, reset and abuse controls.

First evidence needed

define the public threat model, operating-cost ceiling, reset isolation, clear sample-data labeling, and a task-completion fixture before hosting anything.

As a new user, I can import supported records from Markdown or Obsidian, Notion, Todoist, Apple Reminders, calendars, GitHub Issues, or Linear while preserving source provenance and reviewing conflicts.

Where it lives

Import assistants, source adapters, preview, mapping, provenance, rollback.

First evidence needed

measure demand by source, document export constraints, and prove preview, deduplication, partial failure, permission, and recoverable rollback before enabling writes.

As a user, I can opt in to privacy-preserving product feedback that records activation outcomes without sending record content, titles, paths, credentials, or stable device identifiers.

Where it lives

Consent settings, event allowlist, local inspection, deletion and export controls.

First evidence needed

define the minimum event schema, retention and aggregation rules, opt-in copy, network failure behavior, and tests that prohibited fields can never leave the runtime.

As a desktop user, I can install and update a signed Forge package through a normal application flow without using a terminal, while keeping data location and rollback choices visible.

Where it lives

Signed desktop packages, installer, updater, data-root selection, rollback.

First evidence needed

choose supported operating systems, document signing and notarization requirements, and test clean install, upgrade, downgrade, failure, uninstall, and data preservation.

As a new user, I can start from a reviewed Forge setup for a concrete outcome and understand exactly which records, links, settings, and permissions it will add.

Where it lives

Starter-pack manifest, preview, scoped install, provenance, removal.

First evidence needed

identify high-demand outcomes and prove manifest validation, permission disclosure, collision handling, versioning, and recoverable removal.

As a user, I can browse a trustworthy gallery of templates and integrations, inspect compatibility and permissions, and install only an explicitly reviewed package.

Where it lives

Gallery metadata, signing and review state, compatibility, install and update contracts.

First evidence needed

define authorship, moderation, signing, version compatibility, security review, reporting, removal, and offline failure requirements before accepting third-party packages.

As an Android user, I can pair a companion, grant Health Connect permissions selectively, and synchronize supported health and movement evidence through the same provider-neutral Forge contracts.

Where it lives

Android companion, Health Connect, pairing, background sync, provider-neutral health API.

First evidence needed

validate user demand and platform coverage, map Health Connect data and permission differences, and require parity tests for pairing, privacy, deduplication, background limits, recovery, and source provenance.