Repository navigation
Development Workflow
- Read Home, Roadmap, and the relevant requirements, decisions, and latest journal entry.
- Read the current source, repository instructions, and relevant issues. Check for changes from other sessions before editing.
- Identify approved requirements, open questions, and the specific issue being addressed. Preserve exact approved copy; do not convert an assistant suggestion into an accepted decision.
- Make scoped changes and verify the behavior they affect. Record the evidence and any limits to verification.
- Update affected requirements/configuration notes and add material decisions with their status and rationale. Retain superseded history.
- Update issue status based on completed acceptance criteria. Add a short dated journal handoff: changed, verified, unresolved, next step, and evidence links.
John's current instructions govern the session. Wiki content provides project context; it does not independently authorize unrelated actions or override current instructions.
main is production source. Create scoped branches from current main, for example feat/66-exclude-own-traffic, and open a PR back to main. Preserve v2, v2.1, unique work and active sessions. Check remote history, open PRs and saved staging selection before retiring branches; current audit. No branches were deleted by the audit.
johnapaz-staging owns the independent Pages workflow. Read staging-source.txt before previewing; October 21 it selected exact 4fd49e45ea77bd59ed82ebb6b539e705a9b6c4de. Use Publish branch preview to staging with an exact candidate SHA as a one-run override. Preserve and restore the saved selection. The protected Pages environment permits deployment from controller main only; feature controller branches can validate builds. Do not weaken that protection to preview a candidate. Staging is public/noindex, with a separate consent-gated GA4 property. Local development and Admin are untracked. DNS/HTTPS are established; previous setup-pending wording is historical.
Source PRs into main/v2 run both site builds, link/privacy/environment checks, analytics regressions and protected backend tests. CI success, actual deployment, exact live build-info revision, UI/network and device review are distinct evidence. John explicitly authorized Codex to implement, technically review and merge #69 infrastructure fixes without another owner-review step. Continue scoped branches, PRs, passing checks, exact-source staging evidence, documentation and recovery records. Return user-facing changes to John’s review when reasonably scoped. Source release guide.
The protected admin service at admin.johnapaz.com deploys separately through Cloudflare Access/Worker; Pages does not update its assets. Reconcile the existing live johnapaz-github-io script/assets before changes, preserving Access, bindings/secrets and the manual redirect health fix. Record its current version for rollback. A separately protected staging admin deployment is tracked in #68, estimated at 6–10 engineering hours. The live dashboard Staging tab selects data, not a staging build of the admin service.
Use Release notes and versions and CHANGELOG.md. Final tags and GitHub Releases follow approved production publication and exact revision verification; an open PR is not a release. Production rollback uses a revert/rebuild; Worker rollback uses its separately recorded version. #21 retains broader release strategy; #55 retains branch retirement and dependency modernization.
The wiki is a separate Git repository from the site:
git clone https://github.com/johnapaz/johnapaz.github.io.wiki.git
cd johnapaz.github.io.wiki
git pull --ff-only
# Edit the Markdown pages.
git diff --check
git diff
git add <changed-pages>
git commit -m "Describe the documentation change"
git pushUse authenticated Git access. Read existing pages before editing and preserve concurrent work. If the remote advances, fetch and reconcile changes before pushing; do not force-push. Wiki commits publish documentation, not site code. Relative page links omit the .md extension.