P1: Reconcile every document and legacy spec with current source #277

Current Priority Decision

Owner direction, 2026-09-13: complete Church/Basketball business workflows and day-to-day operations for every role first; billing and platform readiness later.

Execution lane: phase: business-flow. Current business milestone: #289.
This section overrides older priority, start conditions, broad dependency order and launch estimates below. Keep the detailed technical recommendations where compatible. Execute only the NOW slice; do not expand a mixed issue into its whole production scope. Record completed slice receipts in #289; keep this issue open while retained later work remains.

NOW

Reconcile the docs actually used to implement/operate the selected business slices: current roadmap, README, Church/Basketball role guides, commands, coverage receipts and relevant instructions. Keep the complete document inventory, but do not require all 176 manual files before the next role workflow.

LATER

Complete every remaining manual/generated/historical document disposition with its appropriate platform/native/feature track. Keep this broad issue open for remaining scope; active-slice acceptance is recorded separately.

Validation stays local. No CI checks, hosted reviewers or Ollama code review. Preserve tenant isolation, real member responses and atomic roster changes. A deferred feature is not permission to expose an unfixed vulnerability. No deployment, paid-provider activation or production sign-off is authorized by this reprioritization.

Before implementation, read #252 and #289; finish one role/work package with tests, local review and affected docs/assets. The earlier completion receipt below covers whole-issue closure, not a requirement to finish every deferred package before the business milestone.

Current Implementation Handoff

Prepared 2026-09-13 for a lower-cost builder at source 21a4a804aa57580451edded04736b1f51aef7e48.
No CI checks. All implementation validation and code review run locally.
Use the shared builder contract and this issue's work packages; no xhigh model or automatic model upgrade is required. This is a detailed recommendation, not a claim that a smaller model cannot make mistakes or that tests have passed.

Risk/review focus: Medium: misleading instructions and incomplete documentation coverage.
Start condition: Start only the NOW work package defined above. Use its local business prerequisites, not the entire older platform-release dependency list.

Source of Truth and Current State

• README.md
• AGENTS.md
• CLAUDE.md
• CONTRIBUTING.md
• docs/INDEX.md
• docs/README.md
• docs/ROADMAP.md
• docs/IMPLEMENTATION_PLAN.md
• specs/
• .specify/
• .claude/
• mobile/README.md

The existing body contains the 176-file manual-document ledger; preserve every entry. Generated client docs are a separate 120-document cohort owned by #191. Static link counts are candidates, not a complete link/semantic certification.

This handoff supersedes stale implementation statements in the background below. Preserve existing successful behavior and tests. Recheck the current branch before editing; the baseline is a source pointer, not permission to discard newer changes.

Dependencies and Ownership

• NOW-slice prerequisite receipts: none for isolated planning/read-only work; only the needed safe/local package must pass, not every platform acceptance item in those tickets. Full-release dependency designs below remain later work.
• Coordinate, but do not wait for entire tickets to close merely to inspect/write isolated tests: P2: Regenerate the mobile API client and validate native release #191, P1: Make README, examples and public site match the product #278, P1: Complete pluggable church and basketball acceptance coverage #279, P1: Refresh and reproduce church and basketball UI screenshots #280, P1: Repair local test entry points, coverage and isolation #281, P1: Align agent runners and templates with local-only delivery #282, P1: Make maintenance and migration tools safe and current #283, P2: Reconcile platform assurances with later release evidence #284, P1: Audit every web journey for usability and failure recovery #285, P1: Prevent incomplete and destructive schedule publication #286.
• The final commands below require P1: Repair local test entry points, coverage and isolation #281's safe local environment or an equivalently verified isolated setup. A missing dependency blocks only the slice that needs it; document that state.
• Shared source/ORM/migration changes are serialized per the master roadmap. Do not start concurrent edits to the same ownership area.

Recommended Decisions

1. Create one structured disposition record per manual file: path, current/historical/generated status, canonical destination, verified source/command references, owner issue, review date/SHA and outcome.
2. Edit by small coherent family: root/current navigation, operational docs, feature docs, nested specs, agent templates, mobile. Prefer scoped corrections and historical banners over deleting useful history.
3. For current docs require true claims and runnable references. For archived docs retain original context with a working supersession pointer; explicitly retire missing historical targets rather than invent files.
4. Validate Markdown relative paths/anchors plus HTML href/src/images using a real parser. Separate external links, generated anchors and intentional historical exceptions in the report.

Small Work Packages

Each item is one reviewable slice, not permission for one giant PR. Add the failing regression first; finish code, tests and affected docs for that slice together. Leave this issue open until all packages and original acceptance criteria are satisfied or explicitly revised by the owner.

• 277.1: Build the ledger from git ls-files, cross-check all 176 entries and assign disposition/owner before editing batches.
• 277.2: Repair root/current docs first, then each remaining family, testing commands against disposable fixtures and linking actual implementation owners.
• 277.3: Handle generated docs via P2: Regenerate the mobile API client and validate native release #191 and reconcile GitHub historical/current pointers without reopening completed history blindly.
• 277.4: Run link/claim checks and rendered review across the entire manifest; close only when every row has an outcome and all dedicated issues supply their evidence.

Required Regression Cases

These are specifications for tests to add/retain, not claimed execution results. Each new negative case must assert unchanged unauthorized state and zero forbidden side effects.

• T277-01: New tracked manual document missing from ledger -> local validator fails.
• T277-02: A missing relative target or HTML image -> failure with exact source/path; a deliberately retired historical link -> explicit exception, not silently ignored.
• T277-03: Historical instructions cannot override current no-CI policy or select obsolete work; new/current docs contain no stale feature completion claims.
• T277-04: Deleting/renaming a document requires all current inbound links to be updated; generated docs remain reproducible.

Local Commands and Evidence

Existing targeted commands (paths checked against the audit source; run only after the stated safe preflight):

git ls-files '*.md' '*.md.disabled'
poetry run pytest tests/unit/test_local_validation_policy.py tests/unit/test_readme_unpark.py -q

Also run the shared formatting/lint/touched-type/unit/full-suite and local review protocol from #252 for the final pushed revision. Add new targeted tests to these commands when implemented. Run API and browser tiers in separate processes. Native, PostgreSQL, image, provider and operator drills require their explicit environment; an unavailable tool/target is blocked/not run, never a pass.

Schema and Compatibility

No application migration. A new local ledger/checker is a proposed artifact, not an existing command; document its supported invocation after implementation.

Stop Conditions

Do not rewrite feature claims that require unapproved product behavior. Mark them unavailable/blocked and link their owner; do not hand-edit generated client docs.

After two failed focused repair attempts without new diagnostic evidence, stop the affected package and post the exact failure, commands, suspected boundary and needed decision. Do not silently broaden scope, weaken tests or upgrade models. A fresh local reviewer checks: Sample every family and verify the full ledger reconciles tracked counts; a banner/search result alone cannot mark a file reviewed.

Completion Receipt

• Work-package and regression IDs above map to changed files and actual results.
• Commands, versions, dates, pass/fail/skip/not-run counts, logs/screenshots and tested head/base SHAs are linked.
• A separate local review records findings and resolution; self-review is labeled if used and is not misrepresented as independent review.
• Affected docs/README/playbooks/screenshots and dependency/roadmap status are reconciled, not left as unnamed follow-ups.
• If implementation is authorized through PR/merge, GitHub reports mergeable and the shared local-evidence requirements are met; reviewer agents never merge.
• No hosted CI check, status attestation, Ollama reviewer, live provider action, deployment, real-data purge or store submission was introduced by implication.

Copyable Builder Prompt

First read this issue's Current Priority Decision and #289. Run only its NOW slice.
If this issue is deferred, report that state instead of starting the older package list.
Implement the next ready work package in tomqwu/SignUpFlow issue #277.
Read its Current Implementation Handoff and #252 Builder Handoff Contract first.
Inspect current source and preserve newer/unrelated changes. Start with the
package's failing regression, then complete code, local tests, local review and
affected docs/assets together. Do not skip acceptance or invent passing evidence.
No CI checks or Ollama code review. Do not deploy, activate providers, purge real
data or submit to stores. Stop and report unmet prerequisites or policy decisions.
Record the package/test IDs and exact reviewed/tested source SHAs before claiming done.

Earlier Audit and Acceptance Context

Parent roadmap: #252. Audit baseline: 21a4a804aa57580451edded04736b1f51aef7e48 (2026-09-13).

No CI checks. All code review, formatting, lint, types, migrations, tests, security scans and artifact validation run locally. Do not add hosted validation, required CI statuses, synthetic success statuses or an Ollama code reviewer. Pages publication is separate. Record commands, environment, results, skips, limitations and reviewed head/base SHAs. Builders merge only after complete local evidence and GitHub mergeability; reviewers never merge.

This is planned work, not an implementation or production-readiness sign-off. The audit did not rerun the application/test suite, deploy, contact delivery/payment providers or validate a native release.

Findings

The tracked documentation inventory contains 296 Markdown-like files: 176 manually maintained and 120 generated client documents. An inline-relative-link scan found 110 distinct file/target candidate failures: 44 across 11 manual files and 66 in generated client docs. This is not an external-link, anchor or HTML-link audit. Only 25 manual files match a historical/supersession notice near the top; a notice alone does not validate the contents.

docs/README.md still contains 20 distinct missing relative targets. docs/IMPLEMENTATION_PLAN.md tells readers to add an already-present timezone field and modify removed frontend paths. API_README, EVENT_ROLES_FEATURE, MULTI_ORG_LIMITATIONS and RBAC_IMPLEMENTATION_COMPLETE reference missing paths. Legacy completion reports/specs must not select new work or establish release readiness.

Work Plan

1. Classify each file below as current/update, historical/archive, superseded/redirect, or generated. Record its canonical replacement, source/test references, owner issue and disposition; do not blanket-delete history.
2. Read retained current content end to end. Reconcile routes, permissions versus scheduling roles, feature state, commands, counts, stack, dates, readiness claims and no-CI policy against source. Assign substantive fixes to the linked implementation issue, not this ledger.
3. Preserve historical context with an obvious dated notice and a working current destination. Retire obsolete task instructions; do not recreate already-shipped fields/features.
4. Fix or explicitly retire unavailable links; validate Markdown links, HTML image/link sources and anchors locally. Do not invent replacement files.
5. Reconcile docs/INDEX.md, docs/README.md, docs/ROADMAP.md, root instructions, nested specs and GitHub roadmap/status together.
6. Reconcile all 91 pre-audit GitHub issues and open PR Sprint 4 follow-up — implement ICS format for /solutions/{id}/export #251 with current source. Keep completed history closed; add clear supersession pointers to obsolete CI/marathon instructions. Every real residual defect gets an open owner issue.
7. Handle all 120 mobile/api_client Markdown files through reproducible generation under P2: Regenerate the mobile API client and validate native release #191, not hand edits.

Acceptance

• All 176 entries have a documented disposition and substantive completion evidence, not just a search hit or new banner.
• All 120 generated documents are accounted for under P2: Regenerate the mobile API client and validate native release #191; broken generated links have an intentional regeneration/template fix.
• Local link validation has zero unexplained missing targets; retired historical references are explicit, non-misleading exceptions.
• No current page or generated agent instruction prescribes CI checks, Ollama code review, nonexistent commands or unsupported production/compliance claims.
• Current README, public site, playbooks, screenshots, security/operations docs and agent files are reconciled through their dedicated issues before this closes.
• Every roadmap task is source-checked and has an owner issue; old percentages/effort totals are not copied as current evidence.

Local Validation

Run the documentation/link/claim checks introduced by this work, preview the rendered Markdown, execute affected examples in a disposable environment, and follow the repository local review/full-suite rules for each shipping PR. This issue does not claim the entire inventory has already had a line-by-line semantic review.

Per-file Completion Ledger

Unchecked means the full current/historical disposition remains to be completed, even where this audit sampled or statically inspected it.

.claude (8)

• .claude/commands/speckit.analyze.md
• .claude/commands/speckit.checklist.md
• .claude/commands/speckit.clarify.md
• .claude/commands/speckit.constitution.md
• .claude/commands/speckit.implement.md
• .claude/commands/speckit.plan.md
• .claude/commands/speckit.specify.md
• .claude/commands/speckit.tasks.md

.github (1)

• .github/copilot-instructions.md

.specify (8)

• .specify/memory/constitution.md
• .specify/templates/agent-file-template.md
• .specify/templates/checklist-template.md
• .specify/templates/feature-progress-template.md
• .specify/templates/plan-template.md
• .specify/templates/project-progress-template.md
• .specify/templates/spec-template.md
• .specify/templates/tasks-template.md

Root (4)

• AGENTS.md
• CLAUDE.md
• CONTRIBUTING.md
• README.md

docs (55)

• docs/API.md
• docs/API_QUICKSTART.md
• docs/API_README.md
• docs/BACKEND_DEBUG.md
• docs/COMPREHENSIVE_TEST_SUITE.md
• docs/DATETIME_ARCHITECTURE.md
• docs/DEBUG_REFACTORING.md
• docs/DEPLOYMENT_GUIDE.md
• docs/DOCKER_DEVELOPMENT.md
• docs/DOCUMENTATION_STATUS.md
• docs/ENVIRONMENT_SETUP.md
• docs/EVENT_ROLES_FEATURE.md
• docs/FINAL_STATUS.md
• docs/IMPLEMENTATION_COMPLETE.md
• docs/IMPLEMENTATION_PLAN.md
• docs/INDEX.md
• docs/LAUNCH_ROADMAP.md
• docs/MULTI_ORG_LIMITATIONS.md
• docs/NEXT_STEPS.md
• docs/QUICK_START.md
• docs/RATE_LIMITING.md
• docs/RBAC_AUDIT.md
• docs/RBAC_IMPLEMENTATION_COMPLETE.md
• docs/README.md
• docs/REFACTORING.md
• docs/ROADMAP.md
• docs/RUNBOOK.md
• docs/SAAS_DESIGN.md
• docs/SECURITY.md
• docs/SECURITY_MIGRATION.md
• docs/SPEC_KIT_SETUP.md
• docs/TESTING.md
• docs/TESTING_ACTION_PLAN.md
• docs/TEST_PERFORMANCE.md
• docs/TEST_STRATEGY.md
• docs/TEST_SUMMARY.md
• docs/USER_STORIES.md
• docs/WORKSPACE_ORGANIZATION.md
• docs/ai-agent-coding-strategy.md
• docs/ai-pr-review.md
• docs/archive/SPEC_KIT_PROGRESS.md
• docs/archive/TECHNICAL_DEBT.md
• docs/features/e2e-invitation-workflow.md
• docs/features/password-reset.md
• docs/playbooks/README.md
• docs/playbooks/basketball.md
• docs/playbooks/church.md
• docs/playbooks/validation.md
• docs/research-log.md
• docs/research/legacy-migrations/README.md
• docs/saas/CODEX_PROVIDER_FALLBACK.md
• docs/saas/EMAIL_INTEGRATION_PLAN.md
• docs/saas/SMOKE_TESTING_EMAIL.md
• docs/saas/STRIPE_INTEGRATION_PLAN.md
• docs/source-repos.md

examples (1)

• examples/README.md

mobile (7)

• mobile/ANDROID_RELEASE.md
• mobile/README.md
• mobile/SMOKE.md
• mobile/TESTFLIGHT.md
• mobile/fastlane/README.md
• mobile/ios/Runner/Assets.xcassets/LaunchImage.imageset/README.md
• mobile/prototype/brand-spec.md

specs (92)

• specs/000-user-onboarding/checklists/requirements.md
• specs/000-user-onboarding/contracts/analytics-api.md
• specs/000-user-onboarding/contracts/checklist-api.md
• specs/000-user-onboarding/contracts/sample-data-api.md
• specs/000-user-onboarding/contracts/wizard-api.md
• specs/000-user-onboarding/data-model.md
• specs/000-user-onboarding/plan.md
• specs/000-user-onboarding/quickstart.md
• specs/000-user-onboarding/research.md
• specs/000-user-onboarding/spec.md
• specs/000-user-onboarding/tasks.md
• specs/001-email-notifications/checklists/requirements.md
• specs/001-email-notifications/contracts/sendgrid-webhooks.md
• specs/001-email-notifications/data-model.md
• specs/001-email-notifications/plan.md
• specs/001-email-notifications/quickstart.md
• specs/001-email-notifications/research.md
• specs/001-email-notifications/spec.md
• specs/001-email-notifications/tasks.md
• specs/011-billing-subscription-system/checklists/requirements.md
• specs/011-billing-subscription-system/contracts/billing-api.md
• specs/011-billing-subscription-system/contracts/webhook-api.md
• specs/011-billing-subscription-system/data-model.md
• specs/011-billing-subscription-system/plan.md
• specs/011-billing-subscription-system/progress.md
• specs/011-billing-subscription-system/quickstart.md
• specs/011-billing-subscription-system/research.md
• specs/011-billing-subscription-system/spec.md
• specs/011-billing-subscription-system/tasks.md
• specs/012-i18n-system/spec.md
• specs/013-production-infrastructure/checklists/requirements.md
• specs/013-production-infrastructure/contracts/backup-restore.md
• specs/013-production-infrastructure/contracts/deployment-api.md
• specs/013-production-infrastructure/contracts/health-check.md
• specs/013-production-infrastructure/plan.md
• specs/013-production-infrastructure/quickstart.md
• specs/013-production-infrastructure/research.md
• specs/013-production-infrastructure/spec.md
• specs/014-security-hardening/checklists/requirements.md
• specs/014-security-hardening/contracts/2fa-api.md
• specs/014-security-hardening/contracts/audit-logging.md
• specs/014-security-hardening/contracts/csrf-protection.md
• specs/014-security-hardening/contracts/password-reset.md
• specs/014-security-hardening/contracts/rate-limiting.md
• specs/014-security-hardening/contracts/session-management.md
• specs/014-security-hardening/plan.md
• specs/014-security-hardening/quickstart.md
• specs/014-security-hardening/research.md
• specs/014-security-hardening/spec.md
• specs/015-monitoring-observability/checklists/requirements.md
• specs/015-monitoring-observability/contracts/alert-configuration-api.md
• specs/015-monitoring-observability/contracts/error-tracking-integration.md
• specs/015-monitoring-observability/contracts/health-check-api.md
• specs/015-monitoring-observability/contracts/log-search-api.md
• specs/015-monitoring-observability/contracts/metrics-api.md
• specs/015-monitoring-observability/contracts/status-page-api.md
• specs/015-monitoring-observability/data-model.md
• specs/015-monitoring-observability/plan.md
• specs/015-monitoring-observability/quickstart.md
• specs/015-monitoring-observability/research.md
• specs/015-monitoring-observability/spec.md
• specs/016-recurring-events-ui/checklists/requirements.md
• specs/016-recurring-events-ui/contracts/bulk-edit-api.md
• specs/016-recurring-events-ui/contracts/calendar-preview-api.md
• specs/016-recurring-events-ui/contracts/recurrence-exceptions-api.md
• specs/016-recurring-events-ui/contracts/recurring-series-api.md
• specs/016-recurring-events-ui/data-model.md
• specs/016-recurring-events-ui/plan.md
• specs/016-recurring-events-ui/quickstart.md
• specs/016-recurring-events-ui/research.md
• specs/016-recurring-events-ui/spec.md
• specs/017-manual-schedule-editing/checklists/requirements.md
• specs/017-manual-schedule-editing/spec.md
• specs/018-mobile-responsive-design/checklists/requirements.md
• specs/018-mobile-responsive-design/spec.md
• specs/019-sms-notifications/checklists/requirements.md
• specs/019-sms-notifications/contracts/preferences-api.md
• specs/019-sms-notifications/contracts/sms-api.md
• specs/019-sms-notifications/contracts/templates-api.md
• specs/019-sms-notifications/contracts/webhooks-api.md
• specs/019-sms-notifications/data-model.md
• specs/019-sms-notifications/plan.md
• specs/019-sms-notifications/quickstart.md
• specs/019-sms-notifications/research.md
• specs/019-sms-notifications/spec.md
• specs/019-sms-notifications/tasks.md
• specs/020-solver-quality-changemin/spec.md
• specs/021-sendgrid-integration/spec.md.disabled
• specs/022-flutter-mobile-app/spec.md
• specs/023-sprint-8-completion/spec.md
• specs/024-sprint-9-completion/spec.md
• specs/COMPLETED-000-safety-verification/spec.md

Delivery Ownership and Cross-links

Suggested owner: Documentation maintainer + backend/mobile reviewers (not yet assigned). Roadmap order: 0 and final reconciliation in 3. Implement in small locally reviewed PRs; no source changes are made by filing this issue.

Related delivery: #278 README/examples/site; #279 playbooks; #280 screenshots; #281 local validation; #282 agent generators; #283 tools; #284 security/ops docs; #285 web UI; #286 publication; #191 generated mobile docs.