diff --git a/AGENTS.md b/AGENTS.md index 7913ddabd28e..da0829f2c792 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -102,3 +102,33 @@ const table = sqliteTable("session", { ## Type Checking - Always run `bun typecheck` from package directories (e.g., `packages/opencode`), never `tsc` directly. + +## 7YA.IO Control Mode + +When the user invokes `7YA CONTROL MODE` or asks to manage 7ya.io, do not rely on chat memory as the source of truth. Use GitHub as the code and deployment system, 7ya.io as the public result, and Datasite as the governance and evidence room. + +Canonical production facts to verify before making changes: + +- Canonical repository: `7guard-io/7ya.io` +- Default branch: `main` +- Production workflow: `.github/workflows/pages.yml` +- Workflow name: `Publish 7YA Production Site` +- Publishing target: GitHub Pages +- Deployment trigger: manual `workflow_dispatch` +- Known blocker: GitHub Actions remains quarantined while issue `#83` is open + +Required operating sequence: + +1. Verify the canonical repository, default branch, production host, deployment workflow, live domain, open blockers, and latest production commit. +2. Read `docs/7YA_OPERATING_CONTRACT.md`, `docs/DEPLOYMENT_RUNBOOK.md`, `docs/LIVE_VERIFICATION_CHECKLIST.md`, and `docs/RELEASE_STATE.json` before changing anything. +3. Inspect the live site and capture before-state evidence for the affected route or component. +4. Use a dedicated branch and pull request. Never work from ZIP files, obsolete repositories, random copies, temporary environments, or remembered assumptions. +5. Make the minimum required change and validate homepage, assets, semantic HTML, metadata, mobile layout, analytics coverage, `/pass/`, `/radar/`, and all required public routes. +6. Review the final diff before integration. +7. Merge only after validation, confirm the merged commit on `main`, and publish only through the currently verified production workflow. +8. Never claim a change is published, live, or fixed until the workflow succeeds and the live site is independently verified on desktop and mobile. +9. Archive commit SHA, pull request, workflow run, screenshots, route results, remaining blockers, and rollback point in Datasite. +10. If instructions conflict, stop the conflicting action and follow the latest verified operating contract stored in the canonical repository and Datasite. + +Do not store raw passwords, deployment tokens, or API keys in ordinary documents. Store only where each secret is managed and who controls it. + diff --git a/docs/7YA_OPERATING_CONTRACT.md b/docs/7YA_OPERATING_CONTRACT.md new file mode 100644 index 000000000000..f628430a997e --- /dev/null +++ b/docs/7YA_OPERATING_CONTRACT.md @@ -0,0 +1,69 @@ +# 7YA.IO Operating Contract + +## Purpose + +7ya.io must be operated from durable infrastructure records, not from chat memory. Chat context may help an operator understand prior work, but it is never the source of truth for repository identity, publishing authority, deployment state, release evidence, or rollback decisions. + +## Canonical Systems + +| System | Role | +| --- | --- | +| GitHub | Code, branches, commits, pull requests, and production deployment | +| 7ya.io | Live public result | +| Datasite | Governance vault, evidence, approvals, release records, and audit trail | +| ChatGPT | Operator that reads current state, edits through GitHub, and verifies the result | +| Chat memory | Helpful context only; never the source of truth | + +Datasite must not be treated as the website editor or deployment platform. It holds institutional memory, approvals, evidence, and control records so operators do not improvise. + +## Canonical Production Facts + +Operators must verify these facts before changing the platform: + +- Canonical repository: `7guard-io/7ya.io` +- Default branch: `main` +- Production workflow: `.github/workflows/pages.yml` +- Workflow name: `Publish 7YA Production Site` +- Publishing target: GitHub Pages +- Deployment trigger: manual `workflow_dispatch` +- Known blocker: GitHub Actions remains quarantined while issue `#83` is open + +## Authority Matrix + +| Area | Authority | +| --- | --- | +| Source edits | GitHub pull requests against `7guard-io/7ya.io` | +| Production publishing | Manual run of `Publish 7YA Production Site` after validation and merge | +| Governance records | Datasite project `7YA.IO Sovereign Control Room` | +| Evidence archive | Datasite evidence folders plus repository release records where appropriate | +| Secrets | Secret manager or platform settings only; documents may record location and owner, not raw values | +| Live truth | Independently verified `https://7ya.io` after workflow success | + +## Non-Forgetting Publishing Protocol + +Every 7ya.io task must follow this sequence: + +1. Identify the canonical repository: confirm `7guard-io/7ya.io`, confirm `main`, and check whether the deployment architecture changed. +2. Inspect production: open the live site, check the exact broken route or component, and record before-state evidence. +3. Read governance: read this operating contract, the deployment runbook, current blockers, and release status. +4. Edit safely: create a dedicated branch, make the minimum required changes, and never edit ZIP files, obsolete repositories, temporary environments, or remembered copies. +5. Validate: run route checks, validate semantic HTML, metadata, mobile layout, assets, `/pass/`, `/radar/`, and all required public routes; review the diff. +6. Integrate: open a pull request, merge only after validation, and confirm the merged commit exists on `main`. +7. Publish: run `Publish 7YA Production Site` manually. Do not claim success merely because code was merged. +8. Verify production: confirm the workflow succeeded, open `https://7ya.io`, test changed routes on mobile and desktop, and confirm the live source contains the intended release. +9. Archive evidence: save commit SHA, workflow run, screenshots, route results, and rollback point in Datasite. + +## Required Final Report + +Every 7ya.io operating task must report: + +- Production status +- Repository and branch used +- Files changed +- Tests completed +- Pull request and commit +- Deployment workflow result +- Live routes verified +- Evidence archived +- Remaining blockers +- Exact rollback point diff --git a/docs/ARCHITECTURE_DECISIONS.md b/docs/ARCHITECTURE_DECISIONS.md new file mode 100644 index 000000000000..dc67f5fcdb6a --- /dev/null +++ b/docs/ARCHITECTURE_DECISIONS.md @@ -0,0 +1,31 @@ +# 7YA.IO Architecture Decisions + +## ADR-001: GitHub Is the Code and Deployment System + +Status: Active + +7ya.io source changes, branches, commits, pull requests, and production deployment are controlled through GitHub. Operators must not treat Datasite, chat tools, ZIP files, temporary environments, or obsolete repositories as the source of code truth. + +## ADR-002: GitHub Pages Is the Production Publishing Target + +Status: Active + +Production publishing targets GitHub Pages through `.github/workflows/pages.yml`, named `Publish 7YA Production Site`, and triggered manually with `workflow_dispatch`. + +## ADR-003: Datasite Is the Governance and Evidence Room + +Status: Active + +Datasite stores governance records, approvals, evidence, release records, incident records, and rollback points. It is not the website editor or deployment platform. + +## ADR-004: Chat Memory Is Not Authoritative + +Status: Active + +Chat memory may provide context but must never be used as the authoritative record for repository identity, deployment architecture, production status, evidence, approvals, or rollback points. + +## ADR-005: Secrets Are Never Stored in Ordinary Documents + +Status: Active + +Documents may record where secrets are managed and who controls them. Raw passwords, deployment tokens, and API keys must remain in approved secret-management systems or platform settings. diff --git a/docs/DEPLOYMENT_RUNBOOK.md b/docs/DEPLOYMENT_RUNBOOK.md new file mode 100644 index 000000000000..0d5ed07cb35c --- /dev/null +++ b/docs/DEPLOYMENT_RUNBOOK.md @@ -0,0 +1,57 @@ +# 7YA.IO Deployment Runbook + +## Production Deployment Model + +- Repository: `7guard-io/7ya.io` +- Default branch: `main` +- Workflow file: `.github/workflows/pages.yml` +- Workflow name: `Publish 7YA Production Site` +- Target: GitHub Pages +- Trigger: manual `workflow_dispatch` + +The production workflow validates the homepage, assets, public routes, GA4 coverage, builds an immutable `dist` artifact, and deploys through GitHub Pages. + +## Pre-Change Checks + +1. Confirm the repository is `7guard-io/7ya.io` and the default branch is `main`. +2. Confirm the production workflow file and workflow name have not changed. +3. Confirm the live domain is `https://7ya.io`. +4. Check open blockers, especially issue `#83` while GitHub Actions is quarantined. +5. Read `docs/7YA_OPERATING_CONTRACT.md`, this runbook, `docs/LIVE_VERIFICATION_CHECKLIST.md`, and `docs/RELEASE_STATE.json`. +6. Capture before-state evidence for the affected live route or component. + +## Change Procedure + +1. Create a dedicated branch from the latest `main`. +2. Make the minimum required changes. +3. Do not edit ZIP exports, obsolete repositories, random copies, or temporary environments. +4. Run available validations and route checks. +5. Inspect the final diff. +6. Open a pull request. +7. Merge only after validation has passed. +8. Confirm the merged commit exists on `main`. + +## Publishing Procedure + +1. Start the `Publish 7YA Production Site` workflow manually with `workflow_dispatch`. +2. Wait for the workflow to complete. +3. Treat a merge without a successful workflow as unpublished. +4. If the workflow fails, keep production status as blocked or failed and archive the failure evidence. + +## Post-Publish Verification + +1. Open `https://7ya.io` on desktop and mobile viewport sizes. +2. Verify the changed routes or components. +3. Verify required public routes, including `/pass/` and `/radar/`. +4. Confirm source, metadata, assets, analytics coverage, and semantic HTML where relevant. +5. Record the production commit, workflow run, route results, screenshots, remaining blockers, and rollback point in Datasite. + +## Rollback Procedure + +1. Identify the last known-good production commit from `docs/RELEASE_STATE.json` and Datasite release records. +2. Open a rollback branch or revert pull request against `main`. +3. Validate the rollback with the same route and asset checks. +4. Merge only after validation. +5. Run the production workflow manually. +6. Verify live production independently before claiming rollback complete. +7. Archive rollback evidence and update release state. diff --git a/docs/LIVE_VERIFICATION_CHECKLIST.md b/docs/LIVE_VERIFICATION_CHECKLIST.md new file mode 100644 index 000000000000..8f9a6aa18746 --- /dev/null +++ b/docs/LIVE_VERIFICATION_CHECKLIST.md @@ -0,0 +1,39 @@ +# 7YA.IO Live Verification Checklist + +Use this checklist before and after publishing. Record evidence in Datasite under `7YA.IO Sovereign Control Room`. + +## Before-State Evidence + +- Capture the current live page for each affected route. +- Record the current production commit if available. +- Record the exact issue, route, viewport, browser, and timestamp. + +## Build and Route Validation + +- Homepage loads successfully. +- Required assets load successfully. +- Public routes exist and return the expected content. +- `/pass/` exists and renders correctly. +- `/radar/` exists and renders correctly. +- Semantic HTML is valid for changed pages. +- Metadata and SEO fields are present for changed pages. +- GA4 coverage remains present where required. +- Mobile layout is checked for changed pages. +- Desktop layout is checked for changed pages. + +## Deployment Verification + +- `Publish 7YA Production Site` completed successfully. +- GitHub Pages deployment points to the intended commit. +- `https://7ya.io` serves the intended release. +- Live source or visible release marker confirms the intended build. + +## Evidence to Archive + +- Pull request URL. +- Commit SHA. +- Workflow run URL and result. +- Screenshots for desktop and mobile checks. +- Route test output. +- Remaining blockers. +- Exact rollback point. diff --git a/docs/RELEASE_STATE.json b/docs/RELEASE_STATE.json new file mode 100644 index 000000000000..fea2892f2c2c --- /dev/null +++ b/docs/RELEASE_STATE.json @@ -0,0 +1,31 @@ +{ + "site": "7ya.io", + "canonical_repository": "7guard-io/7ya.io", + "default_branch": "main", + "production_workflow": { + "path": ".github/workflows/pages.yml", + "name": "Publish 7YA Production Site", + "trigger": "workflow_dispatch", + "target": "GitHub Pages" + }, + "governance_room": { + "system": "Datasite", + "project": "7YA.IO Sovereign Control Room", + "status": "required; create when supported offering type is available" + }, + "known_blockers": [ + { + "system": "GitHub Actions", + "issue": "#83", + "status": "quarantined until resolved" + } + ], + "latest_verified_production": { + "commit": null, + "workflow_run": null, + "verified_at": null, + "verified_routes": [] + }, + "rollback_point": null, + "last_updated": "2026-07-12" +}