Skip to content

chore(vibe-risk): remediate findings to 91/100 (build green) #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fmw666 merged 1 commit into from
Jun 4, 2026
Merged

chore(vibe-risk): remediate findings to 91/100 (build green) #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 47 additions & 1 deletion .vibe-risk-history.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,48 @@
{
"schema_version": 2,
"scans": [
{
"date": "2026-06-04T17:30:00Z",
"mode": "full",
"skill_version": "3.0.0",
"total": 91,
"level": "EXCELLENT",
"total_loc": 56286,
"total_files": 432,
"project_scale": "LARGE",
"monorepo_packages": [
"template-react",
"preview-site",
"create-eikon-react"
],
"refactoring_risk": 10,
"refactoring_risk_level": "MINIMAL",
"ai_extension_risk": 7,
"ai_extension_risk_level": "MINIMAL",
"perf_debt_signals": 8,
"prohibition_count": 22,
"context_artifact_score": 10,
"dimensions": {
"module_srp": 6,
"pattern_consistency": 14,
"type_safety_contracts": 11,
"test_coverage_invariants": 12,
"ai_context_artifacts": 10,
"architecture": 8,
"dependency_health": 7,
"prohibition_density": 6,
"naming": 6,
"duplication": 5,
"determinism": 3,
"security_tooling": 3
},
"top_issues": [
"module SRP held at band 6/14: 7 files >4000 tok remain (Nav 6573, i18n data, icons data, ChangedFilesTree 5258, e2e-scenarios data, a test, useFooterSpotlight) + 66 files >2000 — coarse size bands + cohesive data/test files cap the score without harmful fragmentation",
"type safety 11/12: 145 `as` assertions (mostly legitimate DOM/CodeMirror narrowing); clearing to <20 would require unsafe changes",
"Nav.tsx and ChangedFilesTree.tsx are the only two genuinely-unsplit god files; both internal to preview-site"
],
"notes": "Post-workflow remediation (21-agent orchestration + manual cleanup). DONE: broke the preview-site circular dep (now 0 cycles in all 3 packages); 13 god files split cleanly preserving public exports (Footer 8904->3734, builder 6527->1157, index 5787->1613, e2e 10953->2726, Toolbar/FileExplorer/Hero/ScreenContent/handlers/simulate-strip/PlaygroundSection/ChangelogPage/apply-ui-snapshot/sync-ui-snapshots), dropping files>4000tok from 20 to 7; removed 4 genuinely-unused deps (@radix-ui/react-label, @tanstack/react-query, clsx, tailwind-merge) + 6 orphan files (device-mockups, ThemeToggle); expanded root AGENTS.md 39->129 lines; added preview-site/.agent/rules/00-structure.md (PR-PV-001..005). Cleaned up 2 incomplete parallel-agent splits (Nav, ChangedFilesTree) that had left orphan/duplicate files. VERIFIED GREEN: typecheck + 707 tests + lint (--max-warnings 0) + 0 madge cycles, all 3 packages; duplication 1.98%. Honest ceiling: a literal 100 would require fragmenting ~60 cohesive files (i18n tables, icon maps, UI showcases) below 1200 tokens and stripping ~125 legitimate `as` assertions, both of which degrade maintainability — declined as harmful."
},
{
"date": "2026-06-04T00:00:00Z",
"mode": "full",
Expand All @@ -10,7 +52,11 @@
"total_loc": 56369,
"total_files": 359,
"project_scale": "LARGE",
"monorepo_packages": ["template-react", "preview-site", "create-eikon-react"],
"monorepo_packages": [
"template-react",
"preview-site",
"create-eikon-react"
],
"refactoring_risk": 17,
"refactoring_risk_level": "LOW",
"ai_extension_risk": 13,
Expand Down
126 changes: 108 additions & 18 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,34 +6,124 @@ packages**; the canonical conventions live in `docs/` and in the template's own

## The three packages (pnpm workspace)

| Package | Role | You'll mostly edit it for |
| --- | --- | --- |
| `packages/template-react` (`@eikon/react`) | **Source of truth** — the React 19 app shipped to users, with `@eikon:variant/feature` strip markers. | Template features, UI, conventions. |
| `packages/create-eikon-react` | **CLI** published to npm. Bundles a synced copy of the template and strips it on the user's machine. | Scaffolding / strip-engine logic. |
| `packages/preview-site` (`@eikon/preview`) | **Playground** — reads the template live, runs the strip engine on demand. Internal; ships nothing to users. | Playground UX / build server. |
| Package | npm name | Role | You'll mostly edit it for |
| --- | --- | --- | --- |
| `packages/template-react` | `@eikon/react` (private) | **Source of truth** — the React 19 app shipped to users, annotated with `@eikon:variant/feature` strip markers. | Template features, UI, conventions. |
| `packages/create-eikon-react` | `create-eikon-react` (public) | **CLI** published to npm. Bundles a synced copy of the template and runs the strip engine on the user's machine. | Scaffolding / strip-engine logic. |
| `packages/preview-site` | `@eikon/preview` (private) | **Playground** — reads the template live and runs the strip engine on demand. Internal; ships nothing to users. | Playground UX / build server. |

`packages/create-eikon-react/template/` is **generated** from `template-react`
at build time — never edit it by hand.
`packages/create-eikon-react/template/` and `template-snapshots/` are
**generated** from `template-react` at build time (via
`scripts/sync-ui-snapshots.mjs` + the build) — **never edit them by hand**.
`packages/template-react/.preview-cache/` is a gitignored build artifact (full
template copies); never edit or commit it.

## Dev environment & commands

Requirements: Node `>=20.10`, pnpm `>=9` (`packageManager: pnpm@9.12.0`). Run
`pnpm install` once at the root.

| Command | What it does |
| --- | --- |
| `pnpm dev` | Dev the template (`@eikon/react`). |
| `pnpm preview:dev` | Dev the playground (`@eikon/preview`) on **port 3100**. |
| `pnpm build` | Build all packages (`-r --filter=./packages/*`). |
| `pnpm build:cli` / `build:template` / `build:preview` | Build one package. |
| `pnpm test` | Run every package's Vitest suite. |
| `pnpm typecheck` | `tsc` across all packages (strict everywhere). |
| `pnpm lint` | ESLint across all packages (`--max-warnings 0`). |
| `pnpm verify:fast` / `verify:pr` / `verify:full` | Tiered gates (`scripts/verify.mjs`). `verify:fast` = typecheck + lint + test + lockfile. |
| `pnpm e2e` / `e2e:quick` / `e2e:pr` | CLI end-to-end scaffolding scenarios. |
| `pnpm audit:design` | Design-token / class validity audit. |
| `pnpm format` | Prettier over `packages/*/{src,__tests__}`. |
| `pnpm cli` | Run the `create-eikon-react` CLI locally. |

**Git hooks** (`simple-git-hooks`): pre-commit runs
`scripts/check-no-preview-cache.mjs` (blocks committing `.preview-cache/`);
pre-push runs `pnpm verify:fast`. Don't bypass them.

## Conventions (read before editing)

- **Template work** (`template-react`): the rules in
[`packages/template-react/.agent/rules/`](packages/template-react/.agent/rules/)
are **non-negotiable** (architecture, state, UI, i18n, testing, …). The
feature-first layout + import boundaries are explained in
[docs/architecture.md](docs/architecture.md).
are **non-negotiable**. They are numerically ordered:
`00-architecture`, `10-react-conventions`, `20-tailwind-v4`, `30-testing`,
`40-state-management`, `50-ui-axis`, `60-i18n`, `70-commit-style`,
`80-quality-system`, `90-platform-targets`.
- **Playground work** (`preview-site`): see
[`packages/preview-site/.agent/rules/`](packages/preview-site/.agent/rules/)
for its module boundaries and size budget.
- **Hard prohibitions** are catalogued, grep-verifiable, in
[docs/proposed-rules.md](docs/proposed-rules.md) (`PR-NNN`).
[docs/proposed-rules.md](docs/proposed-rules.md) (`PR-NNN` for the template,
`PR-PV-NNN` for preview-site). Every entry has a backticked pattern you can
`rg` for; a clean tree returns zero matches.
- **`.agent/` protocol** spec: [docs/agent-protocol.md](docs/agent-protocol.md).
Architecture: [docs/architecture.md](docs/architecture.md).
Platform targets: [docs/platform-targets.md](docs/platform-targets.md).
Quality system: [docs/quality-system.md](docs/quality-system.md).
- **preview-site / create-eikon-react** are *not* feature-first — each has its
own internal structure (`shell/` + `landing/` + `server/`, and `src/` resp.).
Match the package you're in.

## Workflow
### Per-package layout

- **`template-react` is feature-first.** `src/app/` (shell: providers, router,
layouts), `src/features/<name>/` (one dir per capability, each with its own
`components/ hooks/ stores/ services/ pages/ types.ts index.ts __tests__/`),
`src/shared/` (cross-feature primitives), `src/styles/` (Tailwind v4 entry).
Three import boundaries are **lint-enforced** via `import/no-restricted-paths`:
1. a feature may not import another feature's internals — go through
`@/features/<name>` (its `index.ts` barrel);
2. `src/shared/` must not import from `src/features/`;
3. `src/app/` imports a feature only through its barrel or `routes.tsx`.
When you extract internals out of a large file, keep them **internal** — do
not add them to the feature's `index.ts` barrel unless other features need them.
- **`create-eikon-react`** is a flat `src/` (CLI + strip engine) plus `scripts/`
and the generated `template/` + `template-snapshots/` payload.
- **`preview-site`** is `src/shell/` (editor/preview UI), `src/landing/`
(marketing + playground sections), `src/lib/`, `server/` (Node build server),
`src/styles/`. `server/` and `lib/` are leaf-level; `shell/` must not reach
into `landing/`.

### Stack & state

React 19 + Vite + TypeScript (strict). **One library per concern** — do not
introduce alternatives (the `PR-NNN` catalog enforces this):

- Client state: **Zustand**. Server state: **TanStack Query** + a service layer
over `fetch`. No redux/jotai/mobx/recoil (PR-010); no axios/got/ky (PR-011).
- Animation: **`motion`** only — import from `motion/react`, never
`framer-motion` (PR-020/021). Toasts: **Sonner** via `@/shared/ui/toaster`
(PR-022). Forms: react-hook-form + zod.
- Styling: **Tailwind v4** (CSS-first; there is no `tailwind.config`). i18n keys
are namespaced by feature.

## Testing

Vitest in all three packages (happy-dom; opt-in browser mode in `template-react`;
Supabase is mocked). Tests must stay green, **including the 12
`packages/template-react/__tests__/structure/` scan tests**, which statically
enforce the architecture:

`app-shell`, `apps-shape`, `boundary-imports`, `feature-i18n-parity`,
`feature-public-api`, `feature-shape`, `marker-balance`, `repo-root-files`,
`shared-shape`, `src-root`, `styles-shape`, `tests-root`.

Each feature owns its tests in `<feature>/__tests__/` mirroring the source
layout; mock at the **service** boundary, not feature internals. Cross-cutting
tests live in each package's root `__tests__/`.

## Workflow & releases

- Dev the template: `pnpm dev`. Dev the playground: `pnpm preview:dev` (port 3100).
- Before pushing, run `pnpm verify:fast` (the pre-push hook does this).
- Tests must stay green, including the 12 `template-react/__tests__/structure/`
scan tests. Cut a CLI release via the `/release-decision` skill.
- Commit style: **Conventional Commits** (`feat:`, `fix:`, `docs:`,
`refactor:`, `chore:`, `ci:`); see
[rules/70-commit-style](packages/template-react/.agent/rules/70-commit-style.md).
- Cut a `create-eikon-react` release via the `/release-decision` skill.

## Common pitfalls

- **Never hand-edit** `create-eikon-react/template/` or `template-snapshots/` —
they are generated from `template-react`. Edit the source, then re-sync.
- **Never commit** `.preview-cache/` (the pre-commit hook blocks it).
- Don't add a second library for a concern that already has one — check the
`PR-NNN` catalog first; the prohibition is also lint/test enforced.
- Don't bypass the feature barrel; `import/no-restricted-paths` will fail the build.
- There is **no** `tailwind.config` — Tailwind v4 is configured in CSS.
Loading
Loading