code/cl8y-docs
5
0
Fork 1
Code Issues 8 Pull requests 2 Projects Releases Packages Wiki Activity

design(docs): program review of docs.cl8y.com architecture #2

New issue
Closed
opened 2026-09-13 05:38:59 +00:00 by PlasticDigits · 3 comments
PlasticDigits commented 2026-09-13 05:38:59 +00:00
Owner
Copy link

Summary

Program review of the docs.cl8y.com architecture produced by #1. This is a review of the architecture document, not a product implement and not a substitute for later PR review of #3.

Parent spec: PlasticDigits/cl8y-marketing#3.

Sequence: #1 architecture (done on a reviewable PR or main) → this issue → #3 v0 implement. Do not apply ready / agent:implement to #3 until this issue records RECOMMEND: ACCEPT (or FIX items landed and re-reviewed).

Current codebase

At filing, code/cl8y-docs is README-only. Reviewers must wait until #1 lands docs/ARCHITECTURE.md and AGENTS.md (AC1–AC4 on #1). If those files are absent, this issue is blocked — comment that and stop. Do not invent an architecture in this ticket.

What to review (after #1)

  • docs/ARCHITECTURE.md — stack, routes, nginx crawl rules, env, headers, CTA, 404, CI, non-goals.
  • AGENTS.md — invariants and the #1 → #2 → #3 gate.
  • README.md — must not claim the site is live.

External truth to check against

  • marketing#3 — product constraints and v0 AC (this review does not implement them).
  • cl8y-marketing/strategy/technical-architecture.md — one deployable = one repo; Vite → nginx; public VITE_* only.
  • cl8y-dex-terraclassic/docker/frontend/nginx.conf — SPA try_files anti-pattern for crawl files (marketing#2).
  • CL8Y-web prerender + src/blog/SEO.tsx + src/lib/siteOrigin.ts — unique titles/canonicals without copying wagmi/three.js.
  • CL8Y-web/src/content/invariants.ts — DEX origin https://dex.cl8y.com; banned current-product copy.

Duplicates / already implemented

Work Status
#1 architecture Prerequisite; not a duplicate
marketing#3 Parent spec; do not re-implement here
marketing#2 DEX crawl files; out of scope
#3 v0 host Gated on this review; do not start
App code in this repo Must still be absent after #1; if present, RECOMMEND: BLOCK

Why the new implementation is needed

A greenfield static host will copy the DEX SPA fallback unless someone independently checks the architecture against the known failure (HTML served as robots.txt / sitemap.xml) and against marketing#3’s non-root, unique-canonical, and CTA rules.

Program review exists so #3 does not start from an unreviewed design. CAC previously queued an implement job on the empty repo; that order is wrong. This issue is the gate.

Constraints and guardrails

  1. Do not implement #3 (no Vite/Docker/nginx/pages). Review text and comments only. FIX means the architecture doc on #1 is updated, then re-reviewed.
  2. Do not apply ready / agent:implement to this issue or to #3 from this work. Labels: research + agent:research.
  3. Verdict format (issue comment, first line): RECOMMEND: ACCEPT | RECOMMEND: FIX | RECOMMEND: BLOCK. Cite docs/ARCHITECTURE.md sections. A bare “lgtm” is not ACCEPT.
  4. ACCEPT only if the document is sufficient for #3 to implement without inventing product policy, and it does not contradict marketing#3 on crawl files, unique HTML, env, headers, or repo boundary.
  5. FIX if gaps are bounded (missing 404 rule, MIME, non-root image, CTA allowlist). List required doc edits; do not silently start coding them as the app.
  6. BLOCK if the architecture copies DEX SPA fallback for crawl paths, allows secrets in VITE_*, places the app in another repo, or requires wallet/trading UI.
  7. Do not publish ops internals (hosts, VMs, Coolify uuids, tokens, queue ids) on this public issue.
  8. Do not write strategy/static-content-architecture.md here (marketing repo). Do not land DEX Sitemap:.
  9. Do not invent fee/TVL/volume claims as “examples.”
  10. Independent from the #1 author. Do not share a chat with the architecture implementer.

Relevant files

Path Role
docs/ARCHITECTURE.md (after #1) Primary review target
AGENTS.md Invariants + gate
README.md Honesty
marketing#3 Spec to check against
cl8y-dex-terraclassic/docker/frontend/nginx.conf Anti-pattern
CL8Y-web/vite.config.ts, src/blog/SEO.tsx, src/lib/siteOrigin.ts Prerender pattern
CL8Y-web/src/content/invariants.ts DEX origin / banned copy
#3 Must remain gated

Recommended direction

  1. Confirm #1 AC1–AC4 (architecture doc exists; no app scaffold in that PR).
  2. Walk marketing#3 constraints against the document (static-only, Node 24, non-root, exact robots/sitemap locations, MIME, unique prerender, CTA URLSearchParams, HTTPS origins, 404 unknown paths, clickjacking/nosniff).
  3. Walk attack table A1–A12 on #1 and the attack table below; each row needs an explicit pass/fail in the review comment.
  4. Check #3 is still one bundled v0 issue (scaffold + crawl + prerender + stubs + CTA + CI) and still unlabeled ready.
  5. Comment verdict. If FIX, require a follow-up commit on the architecture PR and a second comment. If ACCEPT, a human may later label #3 ready + agent:implement — this review must not apply those labels.

Acceptance criteria

  • AC1. Review waited until docs/ARCHITECTURE.md from #1 is reviewable (PR or main).
  • AC2. Issue comment starts with RECOMMEND: ACCEPT, RECOMMEND: FIX, or RECOMMEND: BLOCK.
  • AC3. Comment maps marketing#3 crawl/unique-HTML/env/headers/CTA/repo-boundary rules to the document (pass/fail per rule).
  • AC4. Comment includes the attack/abuse table below with pass/fail.
  • AC5. No application code, Dockerfile, or nginx landed by this issue.
  • AC6. #3 was not labeled ready / agent:implement by this work.
  • AC7. Gaps (if FIX) are filed as required edits to #1’s document, not as a second competing architecture issue.

Test plan (functional paths)

# Path Expect
T1 #1 files present docs/ARCHITECTURE.md + AGENTS.md; else stop (blocked)
T2 Repo file list after #1 Still no Vite app / Dockerfile (else BLOCK)
T3 Stack Node 24, Vite, React, TS, nginx; no Node server / Postgres
T4 Routes named Home, methodology(+child), markets, contracts, guides(+child)
T5 Crawl robots text/plain; sitemap application/xml; missing → 404
T6 Prerender Unique title + canonical per path in built HTML
T7 CTA Compile-time VITE_DEX_ORIGIN; URLSearchParams; no visitor-query origin
T8 CI plan gitleaks + unit + Playwright 5 workers called out for #3
T9 #3 gate text Still blocked on this ACCEPT
T10 Independent review Comment is not a rubber-stamp of #1’s own AC checkboxes

Test plan (attack, hack, and abuse)

# Vector Expect
A1 SPA fallback serves HTML as robots/sitemap Architecture must forbid; else FIX/BLOCK
A2 Content-Type lie (HTML labeled text/plain) MIME + body sniff required in #3 tests; called out here
A3 Sitemap loc to phishing / DEX / javascript: Allowlist https://docs.cl8y.com
A4 CTA from window.location.search (open redirect) Forbidden
A5 utm_* / from/to with javascript:, data:, //evil Ignored / never emitted
A6 Secrets in VITE_* or git None
A7 Wallet/WC/trading UI copied from CL8Y-web or DEX Out of scope; BLOCK if required by architecture
A8 Unverified fee/APR/volume in architecture examples Fail
A9 Missing clickjacking / nosniff FIX
A10 Container root Non-root required
A11 Unknown path 200 with home canonical Forbidden
A12 Reviewer starts #3 or applies ready Forbidden
A13 DEX robots Sitemap: to docs before live sitemap Remains gated on marketing#2 + production curl
A14 Architecture PR smuggles the full app BLOCK; revert to docs-only
A15 Path traversal / autoindex in planned nginx Root confined to dist; no autoindex

Verification criteria

  • One review comment with the RECOMMEND line and evidence (file sections, marketing#3 rule ids).
  • Attack table filled.
  • git ls-files still docs-only if ACCEPT of #1; if #1 already merged app code, BLOCK.
  • #3 remains a gated feature issue without ready.
  • No secrets or ops internals in the comment.

Out of scope

  • Implementing the static site (#3).
  • Coolify hostname attach, SKU, snapshots.
  • DEX robots/sitemap files (marketing#2).
  • Marketing-repo strategy file.
  • Wallet, trading, Postgres, paid media.

First-pass model recommendation

Recommendation: grok-high. Cross-repo security review (crawl cloaking, open redirects, secrets, clickjacking) against a new host. Not Composer.

Gate

Blocked until #1 AC1–AC4. #3 stays blocked until this issue’s AC2 is ACCEPT (or FIX cycle complete).

## Summary **Program review** of the docs.cl8y.com architecture produced by [#1](https://git.cl8y.com/code/cl8y-docs/issues/1). This is a review of the **architecture document**, not a product implement and not a substitute for later PR review of #3. Parent spec: [PlasticDigits/cl8y-marketing#3](https://git.cl8y.com/PlasticDigits/cl8y-marketing/issues/3). Sequence: **#1 architecture (done on a reviewable PR or `main`) → this issue → [#3](https://git.cl8y.com/code/cl8y-docs/issues/3) v0 implement.** Do not apply `ready` / `agent:implement` to #3 until this issue records **RECOMMEND: ACCEPT** (or FIX items landed and re-reviewed). ## Current codebase At filing, `code/cl8y-docs` is README-only. Reviewers **must wait** until #1 lands `docs/ARCHITECTURE.md` and `AGENTS.md` (AC1–AC4 on #1). If those files are absent, this issue is blocked — comment that and stop. Do not invent an architecture in this ticket. ### What to review (after #1) - `docs/ARCHITECTURE.md` — stack, routes, nginx crawl rules, env, headers, CTA, 404, CI, non-goals. - `AGENTS.md` — invariants and the #1 → #2 → #3 gate. - `README.md` — must not claim the site is live. ### External truth to check against - [marketing#3](https://git.cl8y.com/PlasticDigits/cl8y-marketing/issues/3) — product constraints and v0 AC (this review does not implement them). - `cl8y-marketing/strategy/technical-architecture.md` — one deployable = one repo; Vite → nginx; public `VITE_*` only. - `cl8y-dex-terraclassic/docker/frontend/nginx.conf` — SPA `try_files` anti-pattern for crawl files ([marketing#2](https://git.cl8y.com/PlasticDigits/cl8y-marketing/issues/2)). - `CL8Y-web` prerender + `src/blog/SEO.tsx` + `src/lib/siteOrigin.ts` — unique titles/canonicals **without** copying wagmi/three.js. - `CL8Y-web/src/content/invariants.ts` — DEX origin `https://dex.cl8y.com`; banned current-product copy. ### Duplicates / already implemented | Work | Status | |------|--------| | #1 architecture | Prerequisite; not a duplicate | | marketing#3 | Parent spec; do not re-implement here | | marketing#2 | DEX crawl files; out of scope | | #3 v0 host | Gated **on this review**; do not start | | App code in this repo | Must still be absent after #1; if present, **RECOMMEND: BLOCK** | ## Why the new implementation is needed A greenfield static host will copy the DEX SPA fallback unless someone independently checks the architecture against the known failure (HTML served as `robots.txt` / `sitemap.xml`) and against marketing#3’s non-root, unique-canonical, and CTA rules. Program review exists so #3 does not start from an unreviewed design. CAC previously queued an **implement** job on the empty repo; that order is wrong. This issue is the gate. ## Constraints and guardrails 1. **Do not implement #3** (no Vite/Docker/nginx/pages). Review text and comments only. FIX means the architecture doc on #1 is updated, then re-reviewed. 2. **Do not** apply `ready` / `agent:implement` to this issue or to #3 from this work. Labels: `research` + `agent:research`. 3. Verdict format (issue comment, first line): `RECOMMEND: ACCEPT` | `RECOMMEND: FIX` | `RECOMMEND: BLOCK`. Cite `docs/ARCHITECTURE.md` sections. A bare “lgtm” is not ACCEPT. 4. **ACCEPT** only if the document is sufficient for #3 to implement without inventing product policy, and it does not contradict marketing#3 on crawl files, unique HTML, env, headers, or repo boundary. 5. **FIX** if gaps are bounded (missing 404 rule, MIME, non-root image, CTA allowlist). List required doc edits; do not silently start coding them as the app. 6. **BLOCK** if the architecture copies DEX SPA fallback for crawl paths, allows secrets in `VITE_*`, places the app in another repo, or requires wallet/trading UI. 7. Do not publish ops internals (hosts, VMs, Coolify uuids, tokens, queue ids) on this public issue. 8. Do not write `strategy/static-content-architecture.md` here (marketing repo). Do not land DEX `Sitemap:`. 9. Do not invent fee/TVL/volume claims as “examples.” 10. Independent from the #1 author. Do not share a chat with the architecture implementer. ## Relevant files | Path | Role | |------|------| | `docs/ARCHITECTURE.md` (after #1) | Primary review target | | `AGENTS.md` | Invariants + gate | | `README.md` | Honesty | | [marketing#3](https://git.cl8y.com/PlasticDigits/cl8y-marketing/issues/3) | Spec to check against | | `cl8y-dex-terraclassic/docker/frontend/nginx.conf` | Anti-pattern | | `CL8Y-web/vite.config.ts`, `src/blog/SEO.tsx`, `src/lib/siteOrigin.ts` | Prerender pattern | | `CL8Y-web/src/content/invariants.ts` | DEX origin / banned copy | | [#3](https://git.cl8y.com/code/cl8y-docs/issues/3) | Must remain gated | ## Recommended direction 1. Confirm #1 AC1–AC4 (architecture doc exists; no app scaffold in that PR). 2. Walk marketing#3 constraints against the document (static-only, Node 24, non-root, exact robots/sitemap locations, MIME, unique prerender, CTA `URLSearchParams`, HTTPS origins, 404 unknown paths, clickjacking/nosniff). 3. Walk attack table A1–A12 on #1 and the attack table below; each row needs an explicit pass/fail in the review comment. 4. Check #3 is still one bundled v0 issue (scaffold + crawl + prerender + stubs + CTA + CI) and still unlabeled `ready`. 5. Comment verdict. If FIX, require a follow-up commit on the architecture PR and a second comment. If ACCEPT, a human may later label #3 `ready` + `agent:implement` — **this review must not apply those labels**. ## Acceptance criteria - [ ] **AC1.** Review waited until `docs/ARCHITECTURE.md` from #1 is reviewable (PR or `main`). - [ ] **AC2.** Issue comment starts with `RECOMMEND: ACCEPT`, `RECOMMEND: FIX`, or `RECOMMEND: BLOCK`. - [ ] **AC3.** Comment maps marketing#3 crawl/unique-HTML/env/headers/CTA/repo-boundary rules to the document (pass/fail per rule). - [ ] **AC4.** Comment includes the attack/abuse table below with pass/fail. - [ ] **AC5.** No application code, Dockerfile, or nginx landed by this issue. - [ ] **AC6.** #3 was not labeled `ready` / `agent:implement` by this work. - [ ] **AC7.** Gaps (if FIX) are filed as required edits to #1’s document, not as a second competing architecture issue. ## Test plan (functional paths) | # | Path | Expect | |---|------|--------| | T1 | #1 files present | `docs/ARCHITECTURE.md` + `AGENTS.md`; else stop (blocked) | | T2 | Repo file list after #1 | Still no Vite app / Dockerfile (else BLOCK) | | T3 | Stack | Node 24, Vite, React, TS, nginx; no Node server / Postgres | | T4 | Routes named | Home, methodology(+child), markets, contracts, guides(+child) | | T5 | Crawl | robots `text/plain`; sitemap `application/xml`; missing → 404 | | T6 | Prerender | Unique title + canonical per path in **built HTML** | | T7 | CTA | Compile-time `VITE_DEX_ORIGIN`; `URLSearchParams`; no visitor-query origin | | T8 | CI plan | gitleaks + unit + Playwright 5 workers called out for #3 | | T9 | #3 gate text | Still blocked on this ACCEPT | | T10 | Independent review | Comment is not a rubber-stamp of #1’s own AC checkboxes | ## Test plan (attack, hack, and abuse) | # | Vector | Expect | |---|--------|--------| | A1 | SPA fallback serves HTML as robots/sitemap | Architecture must forbid; else FIX/BLOCK | | A2 | Content-Type lie (HTML labeled text/plain) | MIME + body sniff required in #3 tests; called out here | | A3 | Sitemap loc to phishing / DEX / `javascript:` | Allowlist `https://docs.cl8y.com` | | A4 | CTA from `window.location.search` (open redirect) | Forbidden | | A5 | `utm_*` / `from`/`to` with `javascript:`, `data:`, `//evil` | Ignored / never emitted | | A6 | Secrets in `VITE_*` or git | None | | A7 | Wallet/WC/trading UI copied from CL8Y-web or DEX | Out of scope; BLOCK if required by architecture | | A8 | Unverified fee/APR/volume in architecture examples | Fail | | A9 | Missing clickjacking / nosniff | FIX | | A10 | Container root | Non-root required | | A11 | Unknown path 200 with home canonical | Forbidden | | A12 | Reviewer starts #3 or applies `ready` | Forbidden | | A13 | DEX robots `Sitemap:` to docs before live sitemap | Remains gated on marketing#2 + production curl | | A14 | Architecture PR smuggles the full app | BLOCK; revert to docs-only | | A15 | Path traversal / autoindex in planned nginx | Root confined to dist; no autoindex | ## Verification criteria - One review comment with the RECOMMEND line and evidence (file sections, marketing#3 rule ids). - Attack table filled. - `git ls-files` still docs-only if ACCEPT of #1; if #1 already merged app code, BLOCK. - #3 remains a gated feature issue without `ready`. - No secrets or ops internals in the comment. ## Out of scope - Implementing the static site (#3). - Coolify hostname attach, SKU, snapshots. - DEX robots/sitemap files (marketing#2). - Marketing-repo strategy file. - Wallet, trading, Postgres, paid media. ## First-pass model recommendation Recommendation: **grok-high**. Cross-repo security review (crawl cloaking, open redirects, secrets, clickjacking) against a new host. Not Composer. ## Gate Blocked until [#1](https://git.cl8y.com/code/cl8y-docs/issues/1) AC1–AC4. [#3](https://git.cl8y.com/code/cl8y-docs/issues/3) stays blocked until this issue’s AC2 is ACCEPT (or FIX cycle complete).
PlasticDigits commented 2026-09-13 06:46:53 +00:00
Author
Owner
Copy link

#1 architecture is on main via merged #4 (8bd03b9). Review targets: docs/ARCHITECTURE.md, docs/INVARIANTS.md, AGENTS.md, README.md. Still no Vite/Docker/nginx/Woodpecker in tree (AC4).

This issue is unblocked. Comment a verdict RECOMMEND: ACCEPT|FIX|BLOCK with marketing#3 mapping and A1–A15. Do not start #3 and do not apply ready / agent:implement.

[#1](https://git.cl8y.com/code/cl8y-docs/issues/1) architecture is on `main` via merged [#4](https://git.cl8y.com/code/cl8y-docs/pulls/4) (`8bd03b9`). Review targets: `docs/ARCHITECTURE.md`, `docs/INVARIANTS.md`, `AGENTS.md`, `README.md`. Still no Vite/Docker/nginx/Woodpecker in tree (AC4). This issue is unblocked. Comment a verdict `RECOMMEND: ACCEPT|FIX|BLOCK` with marketing#3 mapping and A1–A15. Do not start [#3](https://git.cl8y.com/code/cl8y-docs/issues/3) and do not apply `ready` / `agent:implement`.
PlasticDigits commented 2026-09-13 07:21:31 +00:00
Author
Owner
Copy link

Do not BLOCK #6 for adding .woodpecker.yaml. The merged #1 text over-blocked CI. Review the architecture document as usual; a pipeline is required (gitleaks + tree now; Node/Playwright still this issue’s gate on #3).

Do **not** BLOCK [#6](https://git.cl8y.com/code/cl8y-docs/pulls/6) for adding `.woodpecker.yaml`. The merged #1 text over-blocked CI. Review the architecture document as usual; a pipeline is required (gitleaks + tree now; Node/Playwright still this issue’s gate on #3).
PlasticDigits commented 2026-09-13 07:33:25 +00:00
Author
Owner
Copy link

RECOMMEND: ACCEPT

Independent program review of code/cl8y-docs at origin/main c296faa (architecture from merged #4, Woodpecker from merged #6). I did not write the architecture, did not implement the app, and did not apply ready / agent:implement to #3.

Review tree: git ls-files on origin/main is docs + skills + README + AGENTS + .woodpecker.yaml + .gitleaks.toml + .gitignore only. Parent spec: PlasticDigits/cl8y-marketing#3.

The document is sufficient for #3 to implement without inventing product policy. It does not contradict marketing#3 on crawl files, unique HTML, env, headers, or repo boundary. No BLOCK vectors (SPA fallback, secrets in VITE_*, app in another repo, wallet UI required). No required architecture edits.

1. Issue #2 AC1–AC7

AC Result Evidence
AC1. Review waited until docs/ARCHITECTURE.md from #1 is reviewable PASS origin/main c296faa. Architecture landed via merged #4 (8bd03b9). Woodpecker follow-up via merged #6. Files present: docs/ARCHITECTURE.md, docs/INVARIANTS.md, AGENTS.md, README.md, three skills.
AC2. Comment starts with RECOMMEND: … PASS First line of this comment.
AC3. Maps marketing#3 crawl / unique-HTML / env / headers / CTA / repo-boundary rules (and constraints 1–16) PASS §2 below.
AC4. Attack/abuse table with pass/fail PASS §3 below (this issue’s A1–A15, not the differently numbered table in ARCHITECTURE §18).
AC5. No application code, Dockerfile, or nginx landed by this issue PASS Review comment only. Tree still has no package.json / Dockerfile / nginx.conf / page TSX.
AC6. #3 not labeled ready / agent:implement by this work PASS #3 labels remain feature only. This review did not change labels.
AC7. Gaps filed as edits to the architecture document PASS No FIX items. No competing architecture issue.

2. marketing#3 mapping

ARCHITECTURE §15 claims constraints 1–16 match §§3–12. Checked against the parent issue body, not that checkbox.

Repo boundary, crawl, unique HTML, env, headers, CTA

Rule Result Architecture cite
One deployable = this repo; not marketing.git / CL8Y-web / DEX PASS §1 table + “One deployable = one repo.” INVARIANTS 2. AGENTS.md.
Static only (no Node server, SSR, Postgres, marketing-core) PASS §3 Output row; §14. INVARIANTS 4.
Honest robots.txt (text/plain, User-agent, not HTML shell) PASS §6 robots.txt body + Content-Type; §7 exact location = /robots.txt.
Honest sitemap.xml (application/xml via default_type, urlset of docs URLs only) PASS §6 sitemap rules; §7 default_type application/xml. Explicitly does not rely on nginx .xml → text/xml.
Missing crawl files → 404, not index.html PASS §7 try_files $uri =404 on exact locations; 404 policy table. INVARIANTS 7.
Unique prerendered <title> + rel=canonical per shipped path PASS §4 route table (unique title seeds + canonicals); §5 SSG file layout + “Do not ship one root index.html title/canonical.” INVARIANTS 10.
Public VITE_* only; fail closed on missing / non-https:// origins PASS §9 table; §8 “Do not copy DEX test -n \"$VITE_WC_PROJECT_ID\".” INVARIANTS 11. Forbids window.location for product/canonical origins (§5, §9, §10).
Headers: X-Frame-Options: DENY, frame-ancestors 'none', nosniff on HTML and crawl files PASS §11; §7 add_header on server + exact crawl locations. Matches CL8Y-web CLICKJACKING_HEADERS.
CTAs: compile-time VITE_DEX_ORIGIN, URLSearchParams, execute ids not tickers, no visitor-query concat PASS §10 (signature, construction, default pair, closed utm_campaign set, Forbidden list). Skill docs-dex-cta.
DEX Sitemap: pointer not in this repo / not #3 PASS §1, §14, INVARIANTS 18. marketing AC11.
strategy/static-content-architecture.md not in this repo PASS §1, §14, INVARIANTS 20. marketing AC12.

Constraints 1–16

# marketing#3 constraint Result Cite
1 One deployable = new code/ repo; not marketing / CL8Y-web / DEX PASS §1
2 Static only PASS §3, §14
3 Node 24 builder PASS §3, §8 FROM node:24-bookworm-slim AS builder
4 nginx non-root, unprivileged port PASS §3 / §8: nginxinc/nginx-unprivileged:1.27-alpine, listen 8080, do not copy DEX nginx:1.27-alpine.
5 No SPA fallback for /robots.txt / /sitemap.xml; sibling paths not HTML 200 PASS §6 sibling 404; §7 exact locations vs DEX SPA try_files.
6 MIME robots text/plain; sitemap application/xml via default_type PASS §6–§7
7 Public build-time env; HTTPS; no WC/LCD/forge secrets; fail if required origins missing PASS §9. Indexer optional; if set must equal https://indexer.dex.cl8y.com.
8 Unique crawler HTML (not one shell title) PASS §4–§5. Names DEX OG-5 anti-pattern.
9 CTAs to https://dex.cl8y.com; from/to execute ids; URLSearchParams; no javascript: / data: / // / ?url= / visitor query / window.location origin PASS §10. Default pair uluna + Terra Classic CL8Y CW20. Docs must not emit exactAmount / exactField. Honest note that DEX drops utm_* on rewrite.
10 No unverified fee / TVL / volume / ranking / “best DEX”; no CoinGecko/CMC marketing PASS §12. /markets forbids figures.
11 Do not publish unpublished marketing content/guides/; stubs OK PASS §4 /guides; §12; §14
12 Out of scope: wallet, trading UI, wrap/mint, pair create, paid media, listings PASS §3 forbidden deps; §14
13 Do not noindex this host from DEX robots PASS §6
14 DEX Sitemap: gated on live docs crawl PASS §1, §14, INVARIANTS 18
15 Clickjacking + nosniff PASS §11, §7
16 Canonical host https://docs.cl8y.com (no trailing slash on origin); www 301 or unpublished PASS §4 Canonical rules; INVARIANTS 16. Home canonical with slash; other paths without.

marketing#3 AC1–AC12 (architecture coverage, not production proof)

AC Result Cite
AC1 one-repo-one-deployable PASS §1, §15
AC2 GET / HTML chrome PASS (specified for #3) §4 /; §3 stack; §16
AC3 /robots.txt text/plain PASS §6–§7, §15
AC4 /sitemap.xml application/xml PASS §6–§7, §15
AC5 missing crawl files 404 PASS §7 404 policy
AC6 unique prerendered titles/canonicals on named routes PASS §4 seven-path allowlist
AC7 DEX CTAs; no secrets PASS §10, §8–§9
AC8 no unverified claims PASS §12
AC9 non-root nginx; hashed 404 PASS §7 @hashed_asset_miss; §8
AC10 Coolify image/tag + hostname; rollback = previous tag; no SKU pick PASS §3 Deploy; §8; §14; INVARIANTS 17
AC11 DEX Sitemap: PASS (out of this repo’s v0) §1, §14, §15
AC12 marketing strategy file PASS (out of this repo) §1, §14, §15

Independently checked siblings:

  • DEX docker/frontend/nginx.conf: SPA try_files $uri $uri/ /index.html on /; exact-location 404 only for /og-image.png. Architecture copies the 404 idea, forbids the SPA /.
  • CL8Y-web/src/lib/siteOrigin.ts: trailing-slash strip plus window.location fallback. Architecture reuses the bake/strip contract and forbids the fallback.
  • invariants.ts: DEX origin, BANNED_CURRENT_COPY, CLICKJACKING_HEADERS match.
  • tokenDirectory.ts addresses in §4 match. uluna is correctly labeled as DEX swap-layer.

3. Attack table A1–A15 (this issue’s numbering)

ARCHITECTURE §18 uses a different A1–A12 numbering. This table is issue #2’s A1–A15.

# Vector Result Architecture must reject/gate
A1 SPA fallback serves HTML as robots/sitemap PASS §7 forbids DEX try_files $uri $uri/ /index.html. Exact location = + try_files $uri =404.
A2 Content-Type lie (HTML labeled text/plain) PASS §6: robots body must contain User-agent, must not be <!doctype or a Vite shell; sitemap root urlset. §16 names body sniff.
A3 Sitemap loc to phishing / DEX / javascript: PASS §6: urlset of only prerendered first-party docs URLs from §4.
A4 CTA from window.location.search (open redirect) PASS §10 Forbidden: no visitor-query concat; compile-time VITE_DEX_ORIGIN.
A5 utm_* / from/to with javascript:, data:, //evil PASS §10 Forbidden those schemes; campaign is a closed vocabulary.
A6 Secrets in VITE_* or git PASS §9 Forbidden VITE_WC_*, LCD, forge, passwords. .woodpecker.yaml gitleaks --exit-code 1.
A7 Wallet/WC/trading UI copied from CL8Y-web or DEX PASS §3 forbidden deps; §14; INVARIANTS 19. Architecture does not require wallet UI.
A8 Unverified fee/APR/volume in architecture examples PASS §12 forbids them. No example numbers stated as facts.
A9 Missing clickjacking / nosniff PASS §11 + §7 headers on HTML and crawl files.
A10 Container root PASS §3 / §8 unprivileged image, uid 101, port 8080, do not USER root.
A11 Unknown path 200 with home canonical PASS §7 location / { try_files $uri $uri/ =404; }.
A12 Reviewer starts #3 or applies ready PASS (process) This review did not start #3 or apply labels.
A13 DEX robots Sitemap: to docs before live sitemap PASS §1 / §14 gated on production curl; marketing#2. Not #3.
A14 Architecture PR smuggles the full app PASS git ls-files on c296faa: no app scaffold. .woodpecker.yaml is required CI, not app scaffold.
A15 Path traversal / autoindex in planned nginx PASS §7: root /usr/share/nginx/html; autoindex off; no alias.

4. Functional T1–T10 (this issue)

# Path Result Evidence
T1 #1 files present PASS docs/ARCHITECTURE.md + AGENTS.md on origin/main.
T2 Repo file list after #1 (+ #6 CI) PASS Still no Vite app / Dockerfile / nginx / page TSX. Woodpecker present is required.
T3 Stack PASS §3: TypeScript strict, React, Vite, Node 24, nginx non-root.
T4 Routes named PASS §4 seven-path allowlist.
T5 Crawl PASS §6–§7.
T6 Prerender PASS §5.
T7 CTA PASS §10.
T8 CI plan PASS §13 + current .woodpecker.yaml gitleaks + tree.
T9 #3 gate text PASS ARCHITECTURE header, AGENTS.md, INVARIANTS 3, README.
T10 Independent review PASS Sibling nginx/SEO/token files were checked. §18 numbering was not copied blindly.

5. git ls-files (origin/main c296faa)

Allowed: docs, skills, README, AGENTS, Woodpecker, gitleaks, gitignore.

Absent (required at architecture time): package.json, Dockerfile, nginx.conf, public/robots.txt, public/sitemap.xml, page TSX.

Woodpecker is present and required. Node/Playwright remain #3.

6. #3 labels

#3 is Open, label feature only. No ready, no agent:implement. This review did not add them.

7. README must not claim the site is live

PASS. README.md: “Status: architecture only. This repository has no application source yet. The hostname is not a shipped first-party static site.”

8. No credentials or unverified performance numbers as facts

PASS. No WalletConnect ids, LCD keys, forge tokens, or operator passwords. §12 forbids fee/TVL/volume/ranking/“best DEX.”

FIX items

None. No required edits to the architecture document.

Non-blocking notes for #3 implementers (not architecture defects):

  • ARCHITECTURE §18’s A1–A12 labels do not match this issue’s A1–A15. Follow this issue / marketing#3 / docs#3 tables at implement time.
  • #3’s “To create .woodpecker.yaml” line is stale: gitleaks + tree already exist. #3 should extend that file with Node 24 + Playwright 5 workers, including crawl body sniff.
  • v0 dexHref should emit only the named default pair and closed campaign set. Do not put the pair contract, BSC, or MegaETH addresses in from/to.

Verdict

RECOMMEND: ACCEPT.

#3 may be labeled ready + agent:implement by a human after this comment. This review does not apply those labels and does not start #3.

RECOMMEND: ACCEPT Independent program review of `code/cl8y-docs` at `origin/main` `c296faa` (architecture from merged #4, Woodpecker from merged #6). I did not write the architecture, did not implement the app, and did not apply `ready` / `agent:implement` to #3. Review tree: `git ls-files` on `origin/main` is docs + skills + README + AGENTS + `.woodpecker.yaml` + `.gitleaks.toml` + `.gitignore` only. Parent spec: [PlasticDigits/cl8y-marketing#3](https://git.cl8y.com/PlasticDigits/cl8y-marketing/issues/3). The document is sufficient for #3 to implement without inventing product policy. It does not contradict marketing#3 on crawl files, unique HTML, env, headers, or repo boundary. No BLOCK vectors (SPA fallback, secrets in `VITE_*`, app in another repo, wallet UI required). No required architecture edits. --- ## 1. Issue #2 AC1–AC7 | AC | Result | Evidence | |----|--------|----------| | **AC1.** Review waited until `docs/ARCHITECTURE.md` from #1 is reviewable | **PASS** | `origin/main` `c296faa`. Architecture landed via merged [#4](https://git.cl8y.com/code/cl8y-docs/pulls/4) (`8bd03b9`). Woodpecker follow-up via merged [#6](https://git.cl8y.com/code/cl8y-docs/pulls/6). Files present: `docs/ARCHITECTURE.md`, `docs/INVARIANTS.md`, `AGENTS.md`, `README.md`, three skills. | | **AC2.** Comment starts with `RECOMMEND: …` | **PASS** | First line of this comment. | | **AC3.** Maps marketing#3 crawl / unique-HTML / env / headers / CTA / repo-boundary rules (and constraints 1–16) | **PASS** | §2 below. | | **AC4.** Attack/abuse table with pass/fail | **PASS** | §3 below (this issue’s **A1–A15**, not the differently numbered table in ARCHITECTURE §18). | | **AC5.** No application code, Dockerfile, or nginx landed by this issue | **PASS** | Review comment only. Tree still has no `package.json` / `Dockerfile` / `nginx.conf` / page TSX. | | **AC6.** #3 not labeled `ready` / `agent:implement` by this work | **PASS** | [#3](https://git.cl8y.com/code/cl8y-docs/issues/3) labels remain `feature` only. This review did not change labels. | | **AC7.** Gaps filed as edits to the architecture document | **PASS** | No FIX items. No competing architecture issue. | --- ## 2. marketing#3 mapping ARCHITECTURE §15 claims constraints 1–16 match §§3–12. Checked against the parent issue body, not that checkbox. ### Repo boundary, crawl, unique HTML, env, headers, CTA | Rule | Result | Architecture cite | |-----|--------|-------------------| | One deployable = this repo; not marketing.git / CL8Y-web / DEX | **PASS** | §1 table + “One deployable = one repo.” INVARIANTS 2. AGENTS.md. | | Static only (no Node server, SSR, Postgres, marketing-core) | **PASS** | §3 Output row; §14. INVARIANTS 4. | | Honest `robots.txt` (`text/plain`, `User-agent`, not HTML shell) | **PASS** | §6 `robots.txt` body + Content-Type; §7 exact `location = /robots.txt`. | | Honest `sitemap.xml` (`application/xml` via `default_type`, urlset of docs URLs only) | **PASS** | §6 sitemap rules; §7 `default_type application/xml`. Explicitly does not rely on nginx `.xml` → `text/xml`. | | Missing crawl files → 404, not `index.html` | **PASS** | §7 `try_files $uri =404` on exact locations; 404 policy table. INVARIANTS 7. | | Unique prerendered `<title>` + `rel=canonical` per shipped path | **PASS** | §4 route table (unique title seeds + canonicals); §5 SSG file layout + “Do not ship one root `index.html` title/canonical.” INVARIANTS 10. | | Public `VITE_*` only; fail closed on missing / non-`https://` origins | **PASS** | §9 table; §8 “Do not copy DEX `test -n \"$VITE_WC_PROJECT_ID\"`.” INVARIANTS 11. Forbids `window.location` for product/canonical origins (§5, §9, §10). | | Headers: `X-Frame-Options: DENY`, `frame-ancestors 'none'`, `nosniff` on HTML **and** crawl files | **PASS** | §11; §7 `add_header` on server + exact crawl locations. Matches `CL8Y-web` `CLICKJACKING_HEADERS`. | | CTAs: compile-time `VITE_DEX_ORIGIN`, `URLSearchParams`, execute ids not tickers, no visitor-query concat | **PASS** | §10 (signature, construction, default pair, closed `utm_campaign` set, Forbidden list). Skill `docs-dex-cta`. | | DEX `Sitemap:` pointer not in this repo / not #3 | **PASS** | §1, §14, INVARIANTS 18. marketing AC11. | | `strategy/static-content-architecture.md` not in this repo | **PASS** | §1, §14, INVARIANTS 20. marketing AC12. | ### Constraints 1–16 | # | marketing#3 constraint | Result | Cite | |---|------------------------|--------|------| | 1 | One deployable = new `code/` repo; not marketing / CL8Y-web / DEX | **PASS** | §1 | | 2 | Static only | **PASS** | §3, §14 | | 3 | Node 24 builder | **PASS** | §3, §8 `FROM node:24-bookworm-slim AS builder` | | 4 | nginx non-root, unprivileged port | **PASS** | §3 / §8: `nginxinc/nginx-unprivileged:1.27-alpine`, listen **8080**, do not copy DEX `nginx:1.27-alpine`. | | 5 | No SPA fallback for `/robots.txt` / `/sitemap.xml`; sibling paths not HTML 200 | **PASS** | §6 sibling 404; §7 exact locations vs DEX SPA `try_files`. | | 6 | MIME robots `text/plain`; sitemap `application/xml` via `default_type` | **PASS** | §6–§7 | | 7 | Public build-time env; HTTPS; no WC/LCD/forge secrets; fail if required origins missing | **PASS** | §9. Indexer optional; if set must equal `https://indexer.dex.cl8y.com`. | | 8 | Unique crawler HTML (not one shell title) | **PASS** | §4–§5. Names DEX OG-5 anti-pattern. | | 9 | CTAs to `https://dex.cl8y.com`; `from`/`to` execute ids; `URLSearchParams`; no `javascript:` / `data:` / `//` / `?url=` / visitor query / `window.location` origin | **PASS** | §10. Default pair `uluna` + Terra Classic CL8Y CW20. Docs must not emit `exactAmount` / `exactField`. Honest note that DEX drops `utm_*` on rewrite. | | 10 | No unverified fee / TVL / volume / ranking / “best DEX”; no CoinGecko/CMC marketing | **PASS** | §12. `/markets` forbids figures. | | 11 | Do not publish unpublished marketing `content/guides/`; stubs OK | **PASS** | §4 `/guides`; §12; §14 | | 12 | Out of scope: wallet, trading UI, wrap/mint, pair create, paid media, listings | **PASS** | §3 forbidden deps; §14 | | 13 | Do not noindex this host from DEX robots | **PASS** | §6 | | 14 | DEX `Sitemap:` gated on live docs crawl | **PASS** | §1, §14, INVARIANTS 18 | | 15 | Clickjacking + `nosniff` | **PASS** | §11, §7 | | 16 | Canonical host `https://docs.cl8y.com` (no trailing slash on origin); www 301 or unpublished | **PASS** | §4 Canonical rules; INVARIANTS 16. Home canonical **with** slash; other paths **without**. | ### marketing#3 AC1–AC12 (architecture coverage, not production proof) | AC | Result | Cite | |----|--------|------| | AC1 one-repo-one-deployable | **PASS** | §1, §15 | | AC2 `GET /` HTML chrome | **PASS** (specified for #3) | §4 `/`; §3 stack; §16 | | AC3 `/robots.txt` `text/plain` | **PASS** | §6–§7, §15 | | AC4 `/sitemap.xml` `application/xml` | **PASS** | §6–§7, §15 | | AC5 missing crawl files 404 | **PASS** | §7 404 policy | | AC6 unique prerendered titles/canonicals on named routes | **PASS** | §4 seven-path allowlist | | AC7 DEX CTAs; no secrets | **PASS** | §10, §8–§9 | | AC8 no unverified claims | **PASS** | §12 | | AC9 non-root nginx; hashed 404 | **PASS** | §7 `@hashed_asset_miss`; §8 | | AC10 Coolify image/tag + hostname; rollback = previous tag; no SKU pick | **PASS** | §3 Deploy; §8; §14; INVARIANTS 17 | | AC11 DEX `Sitemap:` | **PASS** (out of this repo’s v0) | §1, §14, §15 | | AC12 marketing strategy file | **PASS** (out of this repo) | §1, §14, §15 | Independently checked siblings: - DEX `docker/frontend/nginx.conf`: SPA `try_files $uri $uri/ /index.html` on `/`; exact-location 404 only for `/og-image.png`. Architecture copies the 404 idea, forbids the SPA `/`. - `CL8Y-web/src/lib/siteOrigin.ts`: trailing-slash strip **plus** `window.location` fallback. Architecture reuses the bake/strip contract and **forbids** the fallback. - `invariants.ts`: DEX origin, `BANNED_CURRENT_COPY`, `CLICKJACKING_HEADERS` match. - `tokenDirectory.ts` addresses in §4 match. `uluna` is correctly labeled as DEX swap-layer. --- ## 3. Attack table A1–A15 (this issue’s numbering) ARCHITECTURE §18 uses a **different** A1–A12 numbering. This table is **issue #2’s** A1–A15. | # | Vector | Result | Architecture must reject/gate | |---|--------|--------|-------------------------------| | **A1** | SPA fallback serves HTML as robots/sitemap | **PASS** | §7 forbids DEX `try_files $uri $uri/ /index.html`. Exact `location =` + `try_files $uri =404`. | | **A2** | Content-Type lie (HTML labeled `text/plain`) | **PASS** | §6: robots body must contain `User-agent`, must not be `<!doctype` or a Vite shell; sitemap root `urlset`. §16 names body sniff. | | **A3** | Sitemap `loc` to phishing / DEX / `javascript:` | **PASS** | §6: urlset of **only** prerendered first-party docs URLs from §4. | | **A4** | CTA from `window.location.search` (open redirect) | **PASS** | §10 Forbidden: no visitor-query concat; compile-time `VITE_DEX_ORIGIN`. | | **A5** | `utm_*` / `from`/`to` with `javascript:`, `data:`, `//evil` | **PASS** | §10 Forbidden those schemes; campaign is a **closed** vocabulary. | | **A6** | Secrets in `VITE_*` or git | **PASS** | §9 Forbidden `VITE_WC_*`, LCD, forge, passwords. `.woodpecker.yaml` gitleaks `--exit-code 1`. | | **A7** | Wallet/WC/trading UI copied from CL8Y-web or DEX | **PASS** | §3 forbidden deps; §14; INVARIANTS 19. Architecture does **not** require wallet UI. | | **A8** | Unverified fee/APR/volume in architecture examples | **PASS** | §12 forbids them. No example numbers stated as facts. | | **A9** | Missing clickjacking / nosniff | **PASS** | §11 + §7 headers on HTML and crawl files. | | **A10** | Container root | **PASS** | §3 / §8 unprivileged image, uid 101, port 8080, do not `USER root`. | | **A11** | Unknown path 200 with home canonical | **PASS** | §7 `location / { try_files $uri $uri/ =404; }`. | | **A12** | Reviewer starts #3 or applies `ready` | **PASS** (process) | This review did not start #3 or apply labels. | | **A13** | DEX robots `Sitemap:` to docs before live sitemap | **PASS** | §1 / §14 gated on production curl; marketing#2. Not #3. | | **A14** | Architecture PR smuggles the full app | **PASS** | `git ls-files` on `c296faa`: no app scaffold. `.woodpecker.yaml` is required CI, not app scaffold. | | **A15** | Path traversal / autoindex in planned nginx | **PASS** | §7: `root /usr/share/nginx/html`; `autoindex off`; no `alias`. | --- ## 4. Functional T1–T10 (this issue) | # | Path | Result | Evidence | |---|------|--------|----------| | **T1** | #1 files present | **PASS** | `docs/ARCHITECTURE.md` + `AGENTS.md` on `origin/main`. | | **T2** | Repo file list after #1 (+ #6 CI) | **PASS** | Still no Vite app / Dockerfile / nginx / page TSX. Woodpecker present is **required**. | | **T3** | Stack | **PASS** | §3: TypeScript strict, React, Vite, Node 24, nginx non-root. | | **T4** | Routes named | **PASS** | §4 seven-path allowlist. | | **T5** | Crawl | **PASS** | §6–§7. | | **T6** | Prerender | **PASS** | §5. | | **T7** | CTA | **PASS** | §10. | | **T8** | CI plan | **PASS** | §13 + current `.woodpecker.yaml` gitleaks + tree. | | **T9** | #3 gate text | **PASS** | ARCHITECTURE header, AGENTS.md, INVARIANTS 3, README. | | **T10** | Independent review | **PASS** | Sibling nginx/SEO/token files were checked. §18 numbering was **not** copied blindly. | --- ## 5. `git ls-files` (`origin/main` `c296faa`) Allowed: docs, skills, README, AGENTS, Woodpecker, gitleaks, gitignore. Absent (required at architecture time): `package.json`, `Dockerfile`, `nginx.conf`, `public/robots.txt`, `public/sitemap.xml`, page TSX. Woodpecker is **present and required**. Node/Playwright remain #3. --- ## 6. #3 labels [#3](https://git.cl8y.com/code/cl8y-docs/issues/3) is **Open**, label **`feature` only**. No `ready`, no `agent:implement`. This review did not add them. --- ## 7. README must not claim the site is live **PASS.** `README.md`: “**Status:** architecture only. This repository has no application source yet. The hostname is not a shipped first-party static site.” --- ## 8. No credentials or unverified performance numbers as facts **PASS.** No WalletConnect ids, LCD keys, forge tokens, or operator passwords. §12 forbids fee/TVL/volume/ranking/“best DEX.” --- ## FIX items None. No required edits to the architecture document. Non-blocking notes for #3 implementers (not architecture defects): - ARCHITECTURE §18’s A1–A12 labels do not match this issue’s A1–A15. Follow **this issue / marketing#3 / docs#3** tables at implement time. - #3’s “To create `.woodpecker.yaml`” line is stale: gitleaks + tree already exist. #3 should **extend** that file with Node 24 + Playwright 5 workers, including crawl **body** sniff. - v0 `dexHref` should emit only the named default pair and closed campaign set. Do not put the pair contract, BSC, or MegaETH addresses in `from`/`to`. --- ## Verdict **RECOMMEND: ACCEPT.** #3 may be labeled `ready` + `agent:implement` by a human after this comment. This review does not apply those labels and does not start #3.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
renovate/configure
No results found.
Labels
Clear labels   
agent:implement
Agent implement gate

  
agent:research
Research gate; skip implement admit

  
docs

   
feature
Product feature; do not apply ready until gates pass

  
ready
Ready for agent pickup

  
research
Design/architecture; not implement

No labels
agent:implement
agent:research
docs
feature
ready
research
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
code/cl8y-docs#2
No description provided.