content(processes.develop): mark PRIMARY; sync diagram + frontend template/conformance + guide-audience rules

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/src/main/resources/content/processes/develop/overview.md

@@ -8,11 +8,15 @@ audience: bcos
 
 How day-to-day work flows from a reported issue to a production decision. **BCOS admin only.**
 
+> **This Guide page is the PRIMARY source of truth for the dev workflow.** The copy in
+> `/source/claude/WAYS-OF-WORKING.md` §2.1 is a **secondary offline fallback** (for when bcos.dev is
+> down). If they ever differ, this page wins — and update the fallback to match.
+
 ## The rule
 **Always work on `develop`, never `main` directly.** Every sub-project repo has branch protection
-on `main`. Before any change, `cd` into the sub-project and confirm you're on `develop` (or a
+on `main`. Confirm you're on `develop` (or a feature branch off it) before any change. Repos that
-feature branch off it). Repos that intentionally stay on `main` (no `develop`): `hiveops-src`,
+intentionally stay on `main` (no `develop`): `hiveops-src`, `hiveops-docs`, `hiveops-release`,
-`hiveops-docs`, `hiveops-release`, `hiveops-devops`.
+`hiveops-devops`.
 
 ## Logical flow
 
@@ -23,12 +27,17 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`):
    │  ◇ agreed valid? → they cut the Gitea issue           │
    └───────────────────────┬───────────────────────────────┘
                            ▼   ← Claude starts here
- ① GITEA ISSUE exists (Bug/Enhancement)     — no issue = don't start
+ ① GITEA ISSUE exists (Bug/Enhancement)          — no issue = don't start
                            ▼
  ② BRANCH GUARD ─ on develop / a branch off it?
         ◇ another session open on a NON-develop branch? → ✋ STOP, flag Johannes
                            ▼
  ③ CODE ─ checkout develop → pull → branch <type>/<issue>-<slug> → change
+        │  ┌─ FRONTEND (mandatory, read platform.frontend-template first) ───────┐
+        │  │  • NEW page  → COPY TablePage / TemplatePage, never from scratch    │
+        │  │  • EXISTING  → FIRST verify it conforms to the template;            │
+        │  │                ◇ drifted? → bring into conformance, don't build on it│
+        │  └─ svelte-template-lint hook enforces the locked components ──────────┘
                            ▼
  ④ LOCAL VERIFY ─ frontend? run local dev server → Johannes eyeballs
         ◇ good? ── no → back to ③
@@ -42,8 +51,8 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`):
         Playwright (frontend) / API + real-JWT sweep (backend)
         ◇ fail? → back to ③
                            ▼ pass
- ⑧ UPDATE THE GUIDE ─ affected module(s), relevant tabs
+ ⑧ UPDATE THE GUIDE ─ affected module(s), relevant tabs (own CI; no manual build)
-        (Customer / Internal / Architect / Testing / Claude)
+        bcos.dev guide = internal / ALL content · prod guide = CUSTOMER modules only
                            ▼
  ⑨ PR develop → main
                            ▼
@@ -53,29 +62,41 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`):
                              └─ defer → next release window ([[processes.release]])
 ```
 
+**Human gates (Johannes):** ② wrong-branch stop · ④ UI sign-off · ⑤ PR approval · ⑥ red-CI notify ·
+⑪ prod decision. **Loop-backs to ③:** ④ verify fail · ⑥ CI red · ⑦ smoke fail.
+
 ## The steps
 
 1. **Gitea issue first.** Work starts from a **Gitea issue** (Bug/Enhancement). No issue = don't
    start. User reports on **feedback.bcos.cloud** are triaged **by Josh / Tristan / Johannes** — if
-   they agree it's valid, *they* cut the Gitea issue. That triage is not Claude's step. See
+   they agree, *they* cut the Gitea issue. That triage is not Claude's step. See
    [[processes.gitea-issues]].
-2. **Branch guard.** Confirm the working tree is on `develop` (or a branch off it). If Johannes has
+2. **Branch guard.** Confirm the tree is on `develop` (or a branch off it). If Johannes has **another
-   **another session open on a non-`develop` branch**, STOP and flag it — never proceed in two
+   session open on a non-`develop` branch**, STOP and flag it — never proceed in two places.
-   places. One session per working tree.
+3. **Code.** `git checkout develop && git pull` → `git checkout -b <type>/<issue>-<slug>` → change.
-3. **Code.** `git checkout develop && git pull` → `git checkout -b <type>/<issue>-<slug>` → make the
+   Describe the plan in one line and edit — no "can I code?" ask; the PR is the review.
-   change. Describe the plan in one line and edit — no "can I code?" ask; the PR is the review.
+   **Frontend — MANDATORY (the #1 recurring double-work miss).** Before touching any `.svelte`, read
+   [[platform.frontend-template]].
+   - **New page:** physically **COPY** the canonical base (`TablePage.svelte` plain tables /
+     `TemplatePage.svelte` badge pages) — never write from scratch — then edit only the allowed bits.
+   - **Existing page (new OR ongoing UI work — FIRST):** **verify it conforms** to the
+     TablePage/TemplatePage structure (`.filter-sidebar`, `.content-frame`, `.table-card` border,
+     active-filter chips, `Pagination` at top-of-table, dark-mode rules). Many pages have **drifted /
+     were never built from the template** — if so, bring it into conformance as part of the work; do
+     NOT build on top of a non-conformant page. The `svelte-template-lint` hook enforces the locks.
 4. **Local verify (UI).** For a **frontend** change, run a **local dev server** (`npm run dev`) so
    Johannes can eyeball it. Proceed only once he confirms it's good.
-5. **PR → `develop` → Johannes approves → Claude merges.** SOC2: he approves in the UI, Claude
+5. **PR → `develop` → Johannes approves → Claude merges.** SOC2: he approves in the UI, Claude merges.
-   merges via API.
+6. **cd-develop CI → wait for GREEN** via **Slack**. Do NOT poll CI (Gitea run-status is buggy). If
-6. **cd-develop CI → wait for GREEN** via the **Slack** notification. Do NOT poll CI (Gitea
+   red, Johannes will notify.
-   run-status is buggy). If it's red, Johannes will notify.
+7. **Smoke test bcos.dev — HARD GATE.** Live bcos.dev URL: **Playwright** (frontend) / **API +
-7. **Smoke test bcos.dev — HARD GATE.** Against the live bcos.dev URL: **Playwright** for a
+   real-JWT curl sweep** (backend) — every endpoint the change touches, expected status **and**
-   frontend change, **API + real-JWT curl sweep** for a backend change — every endpoint the change
+   parseable body. "Deployed" is forbidden without this.
-   touches, expected status **and** parseable body. "Deployed" is forbidden without this.
 8. **Update the Guide.** For the module(s) affected, update the relevant **tabs** per what actually
-   changed (endpoints, tables, behaviour, how-to-test) so testers and the team read current docs.
+   changed. `hiveops-guide` has its **own cd-develop CI** (push develop → build → deploy bcos.dev →
-   Sync it now, at the bcos.dev-for-testers stage.
+   smoke → Slack) — do NOT manual-build. **Audience rule:** the **bcos.dev guide is internal (ours),
+   ALL content**; the **production guide (`guide.bcos.cloud`) gets ONLY customer-audience modules** —
+   `processes.*`, `technical.*`, and `audience: bcos`/`internal` tabs never ship to prod.
 9. **PR `develop` → `main`.**
 10. **Reconcile the issue** and place it in the target **milestone** (e.g. `2026-08`). Use `Refs #N`
     in PRs, never `Fixes/Closes #N` (auto-close bypasses the Verify Fix → Tristan gate). Assign by
@@ -83,9 +104,6 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`):
 11. **Prod decision.** Decide **together**: manual build + deploy to production now
     ([[processes.main]]), or leave it for the next release window ([[processes.release]]).
 
-**Human gates (Johannes):** ② stop-if-wrong-branch · ④ local UI sign-off · ⑤ PR approval ·
-⑥ red-CI notify · ⑪ prod decision. **Loop-backs to ③:** ④ verify fail, ⑥ CI red, ⑦ smoke fail.
-
 ## Conventions
 - Conventional commits: `feat(scope): …`, `fix`, `chore`, `docs`, `content`; end with the
   `Co-Authored-By: Claude …` line.
@@ -93,5 +111,6 @@ feature branch off it). Repos that intentionally stay on `main` (no `develop`):
 
 ## Do NOT
 - Do NOT commit directly to `main` or bypass branch protection.
-- Do NOT skip the bcos.dev smoke test (step 7) or the Guide update (step 8) before promoting.
+- Do NOT skip the bcos.dev smoke test (⑦) or the Guide update (⑧) before promoting.
-- Do NOT triage feedback or cut issues off your own bat — that's the human Feedback gate.
+- Do NOT write a frontend page from scratch or build on a non-conformant one (③).
+- Do NOT triage feedback or cut issues yourself — that's the human Feedback gate.