AidOrbit Canonical User Story Development Plan

Last updated: 2026-08-10

Purpose

This is the canonical, checklist-driven user story plan for AidOrbit development. It consolidates the useful requirements from docs/front-end-plan.md, the journey-first product contract under docs/product/, implemented product surfaces, internal audits, and newly identified volunteer-platform needs.

The user-story and backlog sections in docs/front-end-plan.md are historical input, not completion authority. When they disagree with this plan, this plan controls future user-story tracking. Current source code remains the authority for what is actually implemented.

No story in this file is considered complete merely because a component, route, seeded dataset, local-storage prototype, API scaffold, test scaffold, or documentation page exists. Existing functionality starts unchecked and may be checked quickly after its complete journey evidence is revalidated.

Product Boundaries

Canonical model: Organization > Program > Mission > Shift/Role > Volunteer > Registration > Attendance > Hours.
User-facing copy uses Mission/Missions. Legacy Opportunity naming is allowed only for internal compatibility.
Program Manager and Program Staff access is assigned-Program scoped unless explicitly broadened.
UI visibility never substitutes for backend/API authorization.
Public, private, invite-only, unpublished, canceled, expired, and cross-Program data remain distinct.
PostgreSQL compatibility is required for SQL, migrations, generated queries, reports, fixtures, and tests.
GoodNearby and WordPress changes must preserve the public visitor journey and the authenticated AidOrbit owner journey.
Program vertical behavior is additive and Program scoped. It must not replace or globally rename the core model.

Cross-Repository Delivery Contract

Use the repository that owns the persona's experience. A shared database, API, embed, or link does not make aidorbit-web the correct frontend for every story.

Repository	Owns	Does not own
`aidorbit-web`	Authenticated Organization, Program Manager, Program Staff, check-in, and administration operations; source-of-truth workflows and authorization; PostgreSQL migrations; APIs and publication-state enforcement that safely serve other surfaces.	The volunteer-facing Mission search, public Organization/Program/Mission portal, or Volunteer self-service experience. Do not add Volunteer Mission-discovery UI here.
`goodnearby-web` / GoodNearby site	The Volunteer portal: public Mission discovery and search, public Organization and Program pages, Mission details, Volunteer account entry and self-service journeys, registration continuity, and volunteer-facing mobile/accessibility behavior.	Staff operations, organization administration, source-of-truth publication controls, or unrestricted cross-organization data. It consumes only scoped, published public data and authorized Volunteer data.
`aidorbit-wordpress`	Marketing/editorial website pages and authorized public-content embeds, referrals, and integrations that point visitors into the GoodNearby Volunteer portal or authenticated AidOrbit operations.	A second Volunteer portal, Mission search index, registration system, or a bypass around AidOrbit authorization/publication rules.

For every story, record the owning repository and any coordinated repositories in the journey contract and completion record. Start implementation in the owner repository; inspect and update another repository only when the end-to-end contract, shared API, embed, navigation, branding, or redirect is affected.

Volunteer discovery rule: volunteers search for and browse Missions on the GoodNearby site, not in aidorbit-web. aidorbit-web may expose the authenticated operational API and publication controls that power GoodNearby, but it must not become a competing Volunteer Mission-search frontend. Where an older AidOrbit public route still exists for compatibility, treat it as a backend/redirect compatibility surface and do not extend it as the Volunteer product experience.

Cross-repository Definition of Done: verify the owner-surface route is reachable, the handoff or embed preserves Organization/Program/Mission scope, both repositories enforce the appropriate authorization and publication boundaries, and documentation links point Volunteers to GoodNearby and staff to AidOrbit.

How To Use This Plan

Select the highest-priority unchecked story whose dependencies are satisfied.
Identify the owning repository using the cross-repository delivery contract, then read the applicable persona, core journey, workflow-state, permissions, edge-case, and E2E guidance under docs/product/.
For non-trivial product changes, create or update a journey contract from docs/product/templates/journey-contract.md.
Inspect the real route, UI, API, persistence, authorization, notification, reporting, mobile, accessibility, and documentation surfaces before editing.
Implement the smallest coherent end-to-end slice.
Add a completion record beneath the story using the template below.
Check the story only after every applicable Definition of Done requirement has evidence.

Do not change [ ] to [x] based only on an older status claim. If a story is partly delivered, leave it unchecked and record the verified portion and remaining gap.

Priority And Status Rules

Priority	Meaning
P0	Core lifecycle, safety, privacy, authorization, data integrity, or release-critical journey.
P1	Important operating capability required for a mature customer workflow.
P2	Specialized persona, differentiation, scale, or advanced workflow.
Discovery	Candidate that needs product validation before implementation commitment.

The checkbox is the canonical status:

[ ] means not verified complete. This includes planned, partial, prototype, implemented-but-unverified, and blocked work.
[x] means the complete user outcome is implemented and the completion record satisfies the Definition of Done.
External credentials, live-provider checks, app-store review, DNS, deployment, customer acceptance, or other manual gates must remain unchecked until actually completed.

Definition Of Done For Every Story

All applicable items below must be satisfied before checking a story:

Completion Record Template

Add this directly beneath a story before marking it complete:

  - Completed: YYYY-MM-DD
  - Journey contract: `path`
  - UI/entry point: `path or route`
  - API/persistence: `controller/service/migration`
  - Authorization/scope: `policy and negative test`
  - Downstream reconciliation: `affected surfaces and evidence`
  - Verification: `commands and result`
  - Documentation: `customer/product doc and Docusaurus path`
  - Remaining external/manual gates: None

If the final line is not None, the story remains unchecked.

P0: Public Discovery And Account Entry

US-PUB-001 — Public portal visibility. As a public visitor, I want to browse only public, published Organizations, Programs, Missions, and calendars so private, invite-only, unpublished, canceled, expired, or unrelated information never leaks.
- Completed: 2026-08-09
- Journey contract: docs/product/journey-contracts/competitive-gap-013-public-portal-visibility.md
- Owning repository: goodnearby-web; coordinated source-of-truth/API repository: aidorbit-web. No WordPress change is required for this closure slice.
- UI/entry point: GoodNearby Volunteer routes /missions, /o/:slug/missions, /o/:slug/missions/:missionSlug, and /o/:slug/calendar consume the server-filtered GoodNearby public payloads. Legacy aidorbit-web /hubs/:orgSlug/... routes are compatibility/API enforcement surfaces, not the Volunteer product experience.
- API/persistence: PortalController delegates public portal list, detail, and calendar reads to PortalRepository; GoodNearbyRepository reads persisted organization, Program, Mission publication, and workflow-state fields. No new persistence schema is needed for this read-only enforcement slice.
- Authorization/scope: PortalRepository and GoodNearbyRepository require public/published visibility, active Program state, and a public Mission workflow state before serializing public list/detail/calendar/feed data. GoodNearbyController now has a persisted-data regression that returns 404 for a private direct Mission URL and removes that Mission from its public list, calendar, and feed. Repository regressions deny private, invite-only, unpublished, canceled, and inactive-Program Mission data.
- Downstream reconciliation: legacy portal lists, details, calendars, featured Mission surfaces, GoodNearby organization/program lists, details, calendars, and marketplace feed share the public predicates; privacy changes stop exposure rather than changing roster, attendance, hours, or notification state.
- Verification: php -l src/Repositories/PortalRepository.php; php -l src/Repositories/GoodNearbyRepository.php; php public/vendor/bin/phpunit tests/Repositories/PortalRepositoryTest.php tests/Repositories/GoodNearbyRepositoryTest.php — passed (72 tests, 325 assertions). goodnearby-web npx tsc --noEmit — passed. goodnearby-web npx playwright test tests/e2e/organization-first-public-routes.spec.ts --project=chromium --workers=1 — passed (4 tests); the same command with --project=mobile-chrome — passed (4 tests). The GoodNearby runner uses its documented runtime Next server in webpack mode instead of serving the stale static out/ directory. node --check public/success/scripts/sync-development-plan.js and npm --prefix public/success run sync:development-plan — passed. npm run docs:check remains blocked by pre-existing frontmatter/orphan errors in unrelated customer docs. Mock fixtures and legacy AidOrbit browser checks are not counted as public-state proof.
- Documentation: updated the journey contract and docs/customer/explanations/public-portals-vs-private-portals.md; canonical plan sync target is public/success/docs/development/user-story-development-plan.md.
- Remaining external/manual gates: None.
US-PUB-002 — Public Mission decision information. As a prospective Volunteer, I want to understand a Mission's schedule, location policy, capacity signal, eligibility, requirements, accessibility, and approval rules before committing.
- Completed: 2026-08-09
- Journey contract: docs/product/journey-contracts/public-mission-decision-information.md covers public discovery/qualification, Program Manager publication, scope, workflow display, edge cases, and verification.
- Owning repositories: aidorbit-web owns the program-scoped publication settings, persistence, authorization, and public API; goodnearby-web owns Volunteer-facing public Mission details. aidorbit-wordpress is unchanged because it is marketing/editorial/embedded delivery, not the Volunteer portal.
- UI/entry points: AidOrbit Mission Builder's editable Mission GoodNearby visibility panel and the Volunteer Hubs Mission settings can author Public accessibility notes. GoodNearby Volunteer routes /missions, /o/:slug/missions, and /o/:slug/missions/:missionSlug remain the discovery/detail product experience; the detail route conditionally renders an Accessibility section before signup. AidOrbit Mission Control is not a Volunteer Mission-search surface.
- API/persistence: PostgreSQL migration 20260809120000_add_public_mission_accessibility_notes.php adds nullable mission_publication_settings.public_accessibility_notes; GoodNearbyRepository::updateMissionSettings persists it and records the existing publication-settings audit event. publicMissionResponse serializes it as public Mission accessibility.notes alongside existing persisted schedule/shifts, privacy-safe location, capacity, requirements, and signup/approval information.
- Authorization/scope: the existing goodnearby_site.manage_public_missions update path requires the Mission's assigned Program scope before persistence; the focused regression denies an unscoped actor. Public serialization remains behind organization/Program/Mission public and published predicates, active Program state, and public Mission workflow state, so it does not source any Volunteer profile accessibility or health data.
- Downstream reconciliation: this is public publication metadata only. It does not mutate eligibility, capacity, registration, roster, attendance, hours, reports, reminders, or approval state; the public detail retains their current backend-derived signals and signup still enforces those states downstream.
- Verification: php -l src/Repositories/GoodNearbyRepository.php; php -l src/database/migrations/20260809120000_add_public_mission_accessibility_notes.php; php public/vendor/bin/phpunit tests/Repositories/GoodNearbyRepositoryTest.php — passed (50 tests, 216 assertions). npm run build:verify — passed. goodnearby-web npx tsc --noEmit — passed. goodnearby-web npx playwright test tests/e2e/organization-first-public-routes.spec.ts --project=chromium --workers=1 — passed (4 tests); the same command with --project=mobile-chrome — passed (4 tests). git diff --check — passed.
- Documentation and Docusaurus: added the journey contract; updated docs/customer/explanations/public-portals-vs-private-portals.md; node --check public/success/scripts/sync-development-plan.js and npm --prefix public/success run sync:development-plan passed, syncing this canonical plan to public/success/docs/development/user-story-development-plan.md. npm run docs:check still has the pre-existing unrelated frontmatter/orphan failures in platform-admin-integration-health.md and platform-accounts-manual-provisioning.md.
- Remaining external/manual gates: None.
US-PUB-003 — Public-to-account continuity. As a prospective Volunteer, I want to create and verify my account from a public Mission or GoodNearby page and return to the same registration journey.
- Completed: 2026-08-09
- Journey contract: docs/product/journey-contracts/public-to-account-continuity.md covers discovery, account creation, email verification, sign-in, return, scope, privacy, stale-Mission, capacity, and approval outcomes.
- Owning repositories: goodnearby-web owns Volunteer public Mission CTAs and authentication return UI; aidorbit-web owns persistent Volunteer account/verification state, audit events, and safe continuation enforcement. aidorbit-wordpress is unchanged because it is not the Volunteer portal or account flow.
- UI/entry points: the GoodNearby public Mission signup panel routes unauthenticated Volunteers to /sign-in?redirect=/o/:org/missions/:mission or /sign-up?redirect=/o/:org/missions/:mission. The GoodNearby auth form returns successful credential or social sign-in to that route; AidOrbit Mission Control remains outside Volunteer discovery.
- API/persistence: JwtAuthController::goodNearbyRegister forces creation of a persistent Volunteer account, verification-token state, volunteer role assignment, and existing registration audit. The GoodNearby registration client sends an explicit verification continuation; the server-generated verification email carries it, and verified Volunteers return to GoodNearby sign-in with the original internal Mission redirect. Account creation alone does not create a registration or alter shift capacity.
- Authorization/scope: continuation URLs are normalized against the existing configured GoodNearby/CORS-origin allowlist before use. verifyEmail sends non-organization accounts only to that allowlisted GoodNearby URL; arbitrary origins fall back to GoodNearby sign-in. Returning Mission signup continues to use existing server-side identity, public visibility, Program eligibility, requirement, capacity, waitlist, and approval checks.
- Downstream reconciliation: no registration, roster, capacity, reminder, attendance, hours, report, or confirmation event occurs until the returned Volunteer explicitly signs up. Existing auth.goodnearby_register and auth.email_verified audit events retain account lifecycle evidence.
- Verification: php -l src/Http/Controllers/JwtAuthController.php; php public/vendor/bin/phpunit tests/Http/Controllers/JwtAuthControllerTest.php — passed (19 tests, 113 assertions), including persistent GoodNearby Volunteer account/role creation and allowlisted Mission continuation. npm run build:verify — passed. goodnearby-web npx tsc --noEmit — passed after regenerating a malformed ignored .next/dev/types cache through the documented test server. goodnearby-web npx playwright test tests/e2e/organization-first-public-routes.spec.ts --project=chromium --workers=1 — passed (4 tests); the same command with --project=mobile-chrome — passed (4 tests), asserting public Mission account CTAs preserve the Mission path. Path-scoped git diff --check — passed; whole-worktree git diff --check remains blocked by unrelated pre-existing whitespace changes.
- Documentation and Docusaurus: added the journey contract and updated docs/customer/goodnearby/goodnearby-setup.md; node --check public/success/scripts/sync-development-plan.js and npm --prefix public/success run sync:development-plan passed, syncing the canonical plan to public/success/docs/development/user-story-development-plan.md. npm run docs:check remains blocked by pre-existing unrelated frontmatter/orphan failures in platform-admin-integration-health.md and platform-accounts-manual-provisioning.md.
- Remaining external/manual gates: None.
US-PUB-004 — Invitation continuity. As an invited Volunteer, I want an invitation or magic link to preserve the correct Organization, Program, Mission, and intended next action.
- Completed implementation: 2026-08-10 — marked complete at requester direction; required manual runtime validation remains open below.
- Journey contract: docs/product/journey-contracts/invitation-continuity.md.
- Owning repositories: aidorbit-web owns invitation issue, persistence, scope validation, and audit; goodnearby-web owns /invitation authentication and continuation. aidorbit-wordpress is unchanged.
- UI/entry point: VolunteerController::inviteVolunteer emails GoodNearby /invitation?token=...; the GoodNearby continuation surface canonicalizes its trailing-slash route back to that token-scoped path before redirecting unauthenticated visitors through sign-up/sign-in or rendering explicit loading, unavailable, and confirmed states. After confirmation, Review secure Mission access routes to /invitation/access, not an unscoped public Mission URL. Existing accounts can request an invitation-specific Email magic link from GoodNearby sign-in. The Program Manager Roster invite dialog loads persisted invitations after reload, available Missions from the selected authorized Program, supports the review/apply/register action choices, and exposes scoped Revoke and Reissue controls. It deliberately says that an invitation does not register the Volunteer.
- API/persistence: PostgreSQL migration 20260809123000_create_volunteer_invitation_handoffs.php persists only a SHA-256 token hash, recipient email, Organization/Program/Mission scope, action, issuer, expiry, revoke, and consume fields. VolunteerController issues a 14-day handoff and VolunteerInvitationHandoffController::consume atomically marks it consumed after server validation. GET /api/public/goodnearby/invitations/active derives secure display context from those consumed rows; no new client-held scope is persisted.
- Authorization/scope: issue, list, revoke, and reissue require assigned Program authority. The list derives authorized Program IDs from Organization Admin/platform authority, Program Staff assignments, or Program-scoped role grants, and never serializes sibling-Program recipient data. Mutating endpoints load the persisted handoff by current Organization and re-check its Program before mutation. A magic-link GoodNearby redirect is permitted only when the hashed handoff is active and bound to the requested email; the Mission Control callback accepts only that protected GoodNearby invitation return, not arbitrary external URLs. GET /api/public/goodnearby/invitations/active requires authentication and returns only the caller's non-revoked, unexpired consumed handoffs after reloading current Program/Mission state. SignupController rejects invite-only Mission signup without an active handoff for the same authenticated user and Mission, both before and inside the capacity transaction. The Mission picker uses the already scoped OpportunityController list; issue independently rejects a Mission outside that Program or in a non-available state. Consume requires a JWT-authenticated user whose email equals the persisted recipient; expired, revoked, consumed, missing Program, and non-public/stale Mission handoffs fail closed. Raw scope is never accepted from browser parameters or storage.
- Downstream reconciliation: consumption neither creates a registration nor changes capacity, roster, attendance, hours, reports, or notifications. The focused persistence regression verifies that signups remains empty and Mission-shift capacity remains unchanged after consumption. It records issue/consume audit events; the destination must still apply server-side signup/eligibility/capacity/approval enforcement.
- Verification: php -l src/Http/Controllers/VolunteerInvitationHandoffController.php; php -l src/Http/Controllers/VolunteerController.php; php -l src/Http/Controllers/MagicLinksController.php; php -l src/Http/Controllers/SignupController.php; php -l src/bootstrap.php; focused handoff/auth suite — passed (55 tests, 363 assertions), including recipient-bound active-handoff redirect allowance, mismatch denial, canceled-Mission fail-closed-without-consumption, no signup/capacity mutation, authenticated-user-only active invitation contexts, and invite-only signup entitlement binding. Full php public/vendor/bin/phpunit tests/Http/Controllers/SignupControllerTest.php — passed (58 tests, 221 assertions), including direct 403 invitation_required with no signup for an invite-only Mission without a consumed handoff. npm run build:verify — passed. goodnearby-web npx tsc --noEmit — passed. With GoodNearby served by Windows-native Node at 127.0.0.1:3100, npx playwright test tests/e2e/volunteer-workspace-routes.spec.ts --config=playwright.dev.config.ts --project=chromium --workers=1 --grep "preserves an invitation handoff" — passed (1 test), and the same command with --project=mobile-chrome — passed (1 test), including the protected /invitation/access view. Those browser assertions intercept application API calls; the PHP suite above supplies persistence/RBAC evidence. Path-scoped git diff --check — passed; whole-worktree check is blocked by unrelated pre-existing whitespace changes.
- Documentation: updated docs/customer/goodnearby/goodnearby-setup.md; canonical Docusaurus sync target is public/success/docs/development/user-story-development-plan.md.
- Remaining implementation gap: None in the checked-in slice; controller, persistence, and browser-contract evidence is recorded above.
- Remaining external/manual gates: Configure and run the AidOrbit application service with its PostgreSQL-backed integration environment, then execute the invite-only handoff, GoodNearby portal, signup, and capacity flow without intercepted API calls. No local AidOrbit service was listening on ports 8000 or 8080 during verification.
US-PUB-005 — Safe public gallery and impact. As a public visitor, I want to view approved public media and privacy-safe impact information without seeing private people, requirements, or operational records.
- Completed: 2026-08-10
- Journey contract: docs/product/journey-contracts/goodnearby-public-gallery-preview-and-full-page.md covers the Public Visitor/Program Manager journeys, display-only workflow state, approval safeguards, privacy edge cases, and test plan.
- Owning repositories: goodnearby-web owns the Volunteer-facing organization and Program gallery routes; aidorbit-web owns the persisted Media Library approval data and server-filtered public payload. aidorbit-wordpress is unchanged because it is not a GoodNearby gallery surface.
- UI/entry points: GoodNearby organization and Program profiles render a six-image PeopleGallery preview with a reachable full-gallery route at /o/:slug/gallery or /o/:slug/programs/:programSlug/gallery; the keyboard-operable gallery viewer exposes image alt text and lazy-loads non-primary images. Empty approval-safe data renders no gallery rather than a seeded or legacy substitute.
- API/persistence: GoodNearbyRepository::publicOrganizationResponse and ::publicProgramResponse read persisted media_assets, versions, and delivery variants through MediaLibraryRepository::listPublic. The display-only slice creates no registrations, attendance, hours, reports, exports, notifications, or audit events. Public impact remains the organization-controlled public impactStatement, not Volunteer, roster, requirements, or operational data.
- Authorization/scope: the unauthenticated query remains organization/Program scoped and returns only public_approved, approved, consent-safe, non-minor, no_minors_visible, non-archived, publicly deliverable assets. Legacy Mission photos and configured external gallery URLs lack this approval record and are omitted; Media Library titles/descriptions are staff metadata and are not serialized as public captions. MediaLibraryControllerTest proves public API filtering for draft, minor-related, unknown-consent, and unreviewed assets; GoodNearbyRepositoryTest proves legacy-photo exclusion and approved-asset-only output.
- Downstream reconciliation: this display-only publication slice does not mutate Mission, registration, attendance, hours, capacity, roster, dashboard, report, export, notification, or audit state. Organization and Program previews and their full-gallery routes consume the same filtered payload, so an asset cannot appear in one public gallery surface but not the other.
- Verification: php -l src/Repositories/GoodNearbyRepository.php — passed. php public/vendor/bin/phpunit tests/Repositories/GoodNearbyRepositoryTest.php tests/Http/Controllers/MediaLibraryControllerTest.php — passed (73 tests, 264 assertions). npm run build:verify — passed. goodnearby-web npx tsc --noEmit — passed. goodnearby-web npx playwright test tests/e2e/organization-first-public-routes.spec.ts --project=chromium --workers=1 --reporter=list — passed; the same route suite with --project=mobile-chrome --workers=1 — passed. Browser reachability is separate from the PHP persistence/authorization evidence and does not rely on its mock API fixture. Path-scoped git diff --check — passed.
- Documentation and Docusaurus: updated docs/customer/goodnearby/goodnearby-setup.md and the gallery journey contract; canonical plan sync target is public/success/docs/development/user-story-development-plan.md.
- Remaining external/manual gates: None.
US-PUB-006 — Accessible mobile discovery. As a public visitor, I want Mission discovery and account entry to work on a phone, with keyboard and assistive technology, without device-only controls or horizontal overflow.
- Implemented and verification-recorded: 2026-08-10. The checkbox remains open because the manual assistive-technology/device gate below has not been performed.
- Journey contract: docs/product/journey-contracts/public-mobile-discovery-accessibility.md
- Owning repositories: goodnearby-web owns public Mission discovery and account-entry UI; aidorbit-web owns the existing filtered public payload and AidOrbit-backed account/continuation boundary. aidorbit-wordpress is unchanged because it does not own the Volunteer portal.
- UI/entry points: GoodNearby's desktop and responsive public navigation now expose Find Missions at /missions. The mobile menu has an explicit control relationship and returns focus to its trigger on Escape. A visible-on-focus skip link targets the shared main-content wrapper. /missions retains a labeled text search and manual city/ZIP filter alongside optional device location; /sign-in and /sign-up retain labeled account fields and the internal Mission return flow.
- API/persistence: no endpoint, schema, or state mutation was added. This display/entry slice continues to use the server-filtered public Mission payload and existing AidOrbit account creation/verification/continuation paths; account entry does not create registrations or consume capacity.
- Authorization/scope: no browser-provided scope is newly trusted. Existing public/published/active Program filtering and safe internal continuation enforcement were re-run in GoodNearbyRepositoryTest and JwtAuthControllerTest (69 tests, 328 assertions).
- Downstream reconciliation: no Mission, Program, registration, roster, capacity, attendance, hours, dashboard, report, export, notification, or audit state changes. Empty search, denied/unavailable location, and account success/error states are explicit; location failure announces the manual city/ZIP fallback instead of requiring a device-only control.
- Verification: goodnearby-web npx tsc --noEmit — passed. goodnearby-web npx playwright test tests/e2e/organization-first-public-routes.spec.ts --project=chromium --workers=1 --reporter=list — passed (5 tests), including skip target, responsive Mission navigation, Escape focus return, keyboard-labeled controls, and overflow checks. The same command with --project=mobile-chrome — passed (5 tests). php public/vendor/bin/phpunit tests/Repositories/GoodNearbyRepositoryTest.php tests/Http/Controllers/JwtAuthControllerTest.php — passed (69 tests, 328 assertions). npm run build:verify — passed.
- Documentation: added the journey contract and updated docs/customer/goodnearby/goodnearby-setup.md; node --check public/success/scripts/sync-development-plan.js and npm --prefix public/success run sync:development-plan passed, syncing the canonical plan to public/success/docs/development/user-story-development-plan.md. npm run docs:check remains blocked by pre-existing missing frontmatter/orphan errors in unrelated platform integration-health and manual-provisioning customer docs.
- Remaining external/manual gates: Use a physical phone and supported screen reader (VoiceOver or TalkBack) to smoke the responsive menu, skip link, text/ZIP search fallback, public Mission CTA, and account error/success announcements. Do not check this story until that evidence is captured.

P0: Volunteer Lifecycle

P0: Program Manager Lifecycle

P0: Program Staff And Check-In Lead

US-PS-001 — Focused assigned work. As Program Staff, I want a dashboard of today's assigned-Program duties without broad Program Manager or Organization Admin controls.
US-PS-002 — Minimum roster access. As a Check-In Lead, I want only the assigned Mission roster and minimum permitted Volunteer information needed for day-of operations.
US-PS-003 — Limited kiosk launch. As a Check-In Lead, I want to launch an authorized kiosk or QR session without receiving unrelated Program administration access.
US-PS-004 — Day-of attendance actions. As authorized Program Staff, I want to check Volunteers in and out, mark no-shows, and record eligible walk-ins without duplicate attendance or hours.
US-PS-005 — Offline reconciliation. As Program Staff, I want pending offline attendance actions, retries, conflicts, and reconciliation state made visible and safe.
US-PS-006 — Exception escalation. As Program Staff, I want to escalate requirements, safety, attendance, Volunteer questions, and missing-checkout exceptions to an authorized manager.
US-PS-007 — Read-only readiness. As Program Staff, I want safe readiness status for assigned work while requirement decisions and sensitive documents remain separately permissioned.
US-PS-008 — Scoped communication. As authorized Program Staff, I want to message the permitted Mission audience and see delivery history without accessing sibling Programs.
US-PS-009 — Recognition recommendation. As Program Staff, I want to recommend recognition or a thank-you follow-up based on verified service without directly changing governed awards.

P0: Organization Administration And Governance

P1: Platform Administration, Billing, And Support

P1: Reporting, API, Mobile, Accessibility, And AI

P2: Guardians, Groups, Education, Emergency Response, Donors, And Compliance

Guardians And Parents

US-GUA-001 — Guardian invitation and identity. As a guardian, I want a secure invitation and identity-verification path tied to the correct dependent.
US-GUA-002 — Consent and co-signing. As a guardian, I want to review and co-sign required waivers and safety policies with an auditable record.
US-GUA-003 — Household readiness. As a guardian, I want to manage permitted dependent availability, transportation notes, emergency contacts, and readiness tasks.
US-GUA-004 — Dependent alerts. As a guardian, I want preference-aware schedule, cancellation, SOS, incident, and missing-checkout alerts affecting my dependent.
US-GUA-005 — Hours and guest review. As a guardian, I want to review permitted dependent or plus-one participation and service hours.

Corporate, School, And Community Group Leads

US-GRP-001 — Cohort onboarding. As a Group Lead, I want to create a cohort, upload and validate a roster, invite members, and monitor onboarding readiness.
US-GRP-002 — Group reservations. As a Group Lead, I want to reserve permitted Mission capacity while each participant retains identity, eligibility, attendance, and hours.
US-GRP-003 — Group logistics. As a Group Lead, I want to coordinate transportation, arrival instructions, accessibility needs, and announcements.
US-GRP-004 — Commitment tracking. As a Group Lead, I want to compare reservations, attendance, approved hours, plus-one participation, and organizational commitments.
US-GRP-005 — Branded group impact. As a Group Lead, I want privacy-safe branded summaries and verifiable service artifacts for leadership.

Academic Service Learning

US-EDU-001 — Course and LMS roster sync. As an Academic Coordinator, I want to import or synchronize course rosters and reconcile identity safely.
US-EDU-002 — Placement and compliance. As an Academic Coordinator, I want to assign approved placements and monitor waivers, background checks, training, and deadlines.
US-EDU-003 — Academic hours. As an Academic Coordinator, I want approved service hours mapped to course outcomes and exported in registrar-compatible formats.
US-EDU-004 — Reflection and grading. As an Academic Coordinator, I want to collect reflections, apply rubrics, and record outcomes without exposing unrelated Volunteer information.
US-EDU-005 — Campus discovery. As an Academic Coordinator, I want a campus-branded public page containing only approved Programs and Missions.

Emergency Response And Municipal Command

US-EMR-001 — Incident activation. As an authorized commander, I want to activate an incident mode and operational period for a selected disaster-response Program.
US-EMR-002 — Spontaneous Volunteer intake. As authorized response staff, I want to identify, credential, classify, approve, assign, or reject spontaneous Volunteers safely.
US-EMR-003 — Deployment assignments. As response leadership, I want to assign qualified Volunteers and resources to incident Missions while preserving availability and chain-of-command scope.
US-EMR-004 — Live situational map. As response leadership, I want scoped live check-ins, location consent, staffing gaps, hazards, SOS indicators, and authorized boundary overrides.
US-EMR-005 — Geo-targeted broadcasts. As response leadership, I want priority communications limited by qualification, availability, location consent, Program, Mission, and operational role.
US-EMR-006 — ICS and logistics. As authorized staff, I want Mission logistics, activity logs, and supported ICS forms tied to the correct incident and operational period.
US-EMR-007 — After-action reporting. As response leadership, I want a scoped after-action package for Missions, assignments, attendance, approved hours, incidents, and improvement actions.

Donors And Funders

US-DON-001 — Impact portfolio. As a donor or funder, I want privacy-safe Program impact, outcomes, trends, and stories tailored to my authorized portfolio.
US-DON-002 — Pledge and allocation. As a donor or funder, I want to pledge or allocate funds transparently through real payment and accounting workflows.
US-DON-003 — Compliance documents. As an authorized funder, I want current audited statements, policies, and evidence without access to unrelated internal documents.
US-DON-004 — Recurring giving. As a donor, I want Stripe-backed recurring donation management and preference-aware impact updates.
US-DON-005 — Funding brief. As an authorized funder or staff member, I want a reviewable funding brief grounded in real scoped outcomes and approved narratives.

Auditors And Compliance Officers

US-AUD-001 — Audit trail review. As an auditor, I want immutable, scoped evidence for approvals, access, exports, financial actions, publications, and corrections.
US-AUD-002 — Compliance checklists. As a compliance officer, I want assigned control checklists, evidence, remediation owners, deadlines, and immutable status history.
US-AUD-003 — Evidence packages. As an auditor, I want governed evidence exports with templates, prerequisites, redaction, retention, delivery state, and audit history.
US-AUD-004 — Policy drift alerts. As a compliance officer, I want actionable alerts when privacy, retention, accessibility, authorization, or other governed controls drift.

P2: External Integrators, Applicants, And Internal Development

External Partners And Integrators

US-INT-001 — Partner credentials. As an integration owner, I want to issue, scope, rotate, revoke, and audit credentials and allowed origins.
US-INT-002 — Webhook management. As an integration owner, I want to configure supported events, verify signatures, inspect attempts, retry failures, and rotate secrets.
US-INT-003 — Sandbox and documentation. As an integration developer, I want safe test data, an API explorer, examples, errors, rate limits, and version guidance.
US-INT-004 — Usage and alerts. As an integration owner, I want request volume, errors, rate limits, delivery health, and anomaly alerts.
US-INT-005 — Embeddable widgets. As a partner webmaster, I want accessible, responsive, branded public widgets limited by publication rules, scoped keys, and allowed origins.
- Implementation recorded: 2026-08-14. The read-only Mission-feed iframe now fails closed unless its bound key has widgets.read, a matching widget type, a configured HTTPS allowed origin, and the relevant organization/Program scope. Public feed SQL requires both a published public portal and public/published Mission publication settings; private, invite-only, unpublished, and missing-publication-data records are excluded before serialization.
- Journey contract: docs/product/journey-contracts/us-int-005-embeddable-widgets.md.
- Owning repository: aidorbit-web; goodnearby-web and aidorbit-wordpress are unchanged because this is an AidOrbit-hosted public iframe and API contract.
- Verification: php public/vendor/bin/phpunit tests/Http/Controllers/WidgetsControllerTest.php passed (3 tests, 8 assertions). PHP syntax checks and npm run build:verify are required before release.
- Remaining external/manual gate: On deployed staging, create a Program-scoped widget key for a real HTTPS partner test origin, embed the generated iframe at desktop and phone widths, and verify public published Missions render while private, invite-only, unpublished, wrong-origin, revoked-key, and out-of-scope Program requests fail closed. Keep this story unchecked until captured.

Applicants And Beneficiaries

US-APP-001 — Application drafts. As an applicant, I want an accessible multi-step application with validation, attachments, and secure saved drafts.
US-APP-002 — Application state. As an applicant, I want submitted, under-review, changes-requested, approved, rejected, withdrawn, and next-action states explained.
US-APP-003 — Required documents. As an applicant, I want to submit and replace permitted documents and understand verification state without seeing staff-only notes.
US-APP-004 — Secure messaging. As an applicant, I want scoped messages, attachments, delivery/read state, and a permanent application history.

Internal Developers And QA

US-DEV-001 — Component guidance. As a developer, I want current design-system documentation, examples, accessibility expectations, and change history.
US-DEV-002 — Feature-flag validation. As QA, I want safe lower-environment feature overrides with precedence, ownership, rollout notes, and reproducible links.
US-DEV-003 — Analytics verification. As QA, I want to inspect product events, runtime errors, provider health, and web-vital signals without using fictional success state.
US-DEV-004 — Journey regression map. As QA, I want every completed user story mapped to unit, integration, RBAC/API, E2E, mobile, accessibility, and PostgreSQL checks.
US-DEV-005 — Release evidence. As a release owner, I want build, migration, security, dependency, documentation, live-provider, and manual acceptance gates recorded honestly.

Discovery Backlog: Validate Before Commitment

These are credible volunteer-platform needs, but they must not be treated as committed implementation until product scope, personas, permissions, state models, and billing implications are approved.

US-DISC-001 — Interview and reference workflow. Validate configurable Volunteer interviews, references, screening decisions, and due-date automation. Discovery contract: docs/product/journey-contracts/us-disc-001-interview-and-reference-workflow.md.
US-DISC-002 — Shift swap and substitute requests. Validate Volunteer-requested swaps, call-outs, replacement eligibility, manager approval, and notification reconciliation.
US-DISC-003 — Flexible service commitments. Validate recurring commitments and Volunteer-proposed service times outside fixed Mission shifts. Discovery contract: docs/product/journey-contracts/us-disc-003-flexible-service-commitments.md.
US-DISC-004 — Expenses and mileage. Validate Volunteer expense, mileage, receipt, approval, reimbursement, export, and retention requirements. Discovery contract: docs/product/journey-contracts/us-disc-004-expenses-and-mileage.md.
US-DISC-005 — Person deduplication and merge. Validate duplicate detection, safe merge, undo/evidence, inactive status, exit reasons, and reactivation.
US-DISC-006 — Equipment and resource custody. Validate issuance, assignment, condition, return, loss, and audit workflows for badges, equipment, or supplies. Discovery contract: docs/product/journey-contracts/us-disc-006-equipment-and-resource-custody.md.
US-DISC-007 — Confidential complaint workflow. Validate Volunteer complaints, safeguarding concerns, whistleblower protection, restricted case access, and escalation policy. Discovery contract: docs/product/journey-contracts/us-disc-007-confidential-complaint-workflow.md.
US-DISC-008 — Volunteer-to-supporter CRM lifecycle. Validate consent-aware synchronization of Volunteer engagement with donor or supporter CRM records. Discovery contract: docs/product/journey-contracts/us-disc-008-volunteer-to-supporter-crm-lifecycle.md.
US-DISC-009 — Volunteer fundraising. Validate Volunteer-led campaigns, peer fundraising, attribution, payment processing, and donor privacy boundaries. Discovery contract: docs/product/journey-contracts/us-disc-009-volunteer-fundraising.md.

Required Development Order

Within each priority, resolve data-scope and state-integrity dependencies before convenience or automation:

Public visibility, identity, assigned Program scope, and direct API denial.
Mission lifecycle, registration, capacity, waitlists, and requirements.
Day-of attendance, checkout exceptions, hours, and correction audit.
Communications, cancellation suppression, reports, exports, and reconciliation.
Organization governance, privacy, billing, integrations, and public-site administration.
Mobile/offline, accessibility, localization, and AI-assisted workflows.
Specialized personas and approved discovery items.

Source Guidance

AGENTS.md
CLAUDE.md
docs/product/README.md
docs/product/01-personas-and-jobs.md
docs/product/02-core-journeys.md
docs/product/03-workflow-states.md
docs/product/04-permissions-and-scope.md
docs/product/05-domain-language.md
docs/product/06-edge-cases-and-invariants.md
docs/product/07-e2e-test-map.md
docs/product/09-pr-journey-checklist.md
docs/product/10-journey-regression-map.md
docs/architecture/aidorbit-vertical-profiles-operating-contract.md
docs/audits/competitive-analysis-current-state/GAP_SUMMARY_FOR_CHATGPT.md
docs/front-end-plan.md as historical input only

Purpose​

Product Boundaries​

Cross-Repository Delivery Contract​

How To Use This Plan​

Priority And Status Rules​

Definition Of Done For Every Story​

Completion Record Template​

P0: Public Discovery And Account Entry​

P0: Volunteer Lifecycle​

P0: Program Manager Lifecycle​

P0: Program Staff And Check-In Lead​

P0: Organization Administration And Governance​

P1: Platform Administration, Billing, And Support​

P1: Reporting, API, Mobile, Accessibility, And AI​

P2: Guardians, Groups, Education, Emergency Response, Donors, And Compliance​

Guardians And Parents​

Corporate, School, And Community Group Leads​

Academic Service Learning​

Emergency Response And Municipal Command​

Donors And Funders​

Auditors And Compliance Officers​

P2: External Integrators, Applicants, And Internal Development​

External Partners And Integrators​

Applicants And Beneficiaries​

Internal Developers And QA​

Discovery Backlog: Validate Before Commitment​

Required Development Order​

Source Guidance​