create-obsession 0.0.0-stage → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +160 -2
- package/bin/README.md +6 -0
- package/bin/obsession.exe +0 -0
- package/bin/obsession.out +0 -0
- package/frontend/README.md +41 -0
- package/frontend/project-type.json +8 -0
- package/frontend/template/.agent/task-scope.example.json +7 -0
- package/frontend/template/.editorconfig +11 -0
- package/frontend/template/.env +2 -0
- package/frontend/template/.env.example +2 -0
- package/frontend/template/.github/dependabot.yml +11 -0
- package/frontend/template/.github/workflows/quality.yml +28 -0
- package/frontend/template/.gitignore.tpl +28 -0
- package/frontend/template/.vscode/extensions.json +3 -0
- package/frontend/template/.vscode/settings.json +13 -0
- package/frontend/template/.vscode/tasks.json +39 -0
- package/frontend/template/AGENTS.md +56 -0
- package/frontend/template/CLAUDE.md +18 -0
- package/frontend/template/README.md.tpl +57 -0
- package/frontend/template/docs/CHAPTER_8_9_10_ENFORCEMENT.md +82 -0
- package/frontend/template/docs/FEATURE_BLUEPRINT.md +164 -0
- package/frontend/template/docs/FRONTEND_ARCHITECTURE.md +132 -0
- package/frontend/template/docs/SECURITY_BASELINE.md +32 -0
- package/frontend/template/docs/STATE_OWNERSHIP.md +33 -0
- package/frontend/template/docs/TASK_PROTOCOL.md +50 -0
- package/frontend/template/docs/TASK_SCOPE.md +35 -0
- package/frontend/template/docs/TECHNOLOGY_AND_CONFIG.md +96 -0
- package/frontend/template/docs/TESTING_AND_GATES.md +109 -0
- package/frontend/template/docs/TESTING_STRATEGY.md +34 -0
- package/frontend/template/docs/UI_STATES.md +26 -0
- package/frontend/template/docs/reference/front-end-structure-course.html +1606 -0
- package/frontend/template/docs/reference/frontend-project-setup-manual.docx +0 -0
- package/frontend/template/e2e/smoke.spec.ts +12 -0
- package/frontend/template/index.html.tpl +13 -0
- package/frontend/template/package.json.tpl +45 -0
- package/frontend/template/playwright.config.ts +18 -0
- package/frontend/template/scripts/check-architecture.mjs +291 -0
- package/frontend/template/scripts/check-architecture.test.mjs +93 -0
- package/frontend/template/scripts/task-scope.mjs +70 -0
- package/frontend/template/scripts/task-scope.test.mjs +46 -0
- package/frontend/template/src/app/NotFoundPage.tsx +5 -0
- package/frontend/template/src/app/RootLayout.tsx +15 -0
- package/frontend/template/src/app/RouteErrorBoundary.tsx +12 -0
- package/frontend/template/src/app/main.tsx +11 -0
- package/frontend/template/src/app/providers.tsx +12 -0
- package/frontend/template/src/app/router.tsx +14 -0
- package/frontend/template/src/app/store.ts +12 -0
- package/frontend/template/src/features/counter/index.ts +2 -0
- package/frontend/template/src/features/counter/model/counterSlice.test.ts +12 -0
- package/frontend/template/src/features/counter/model/counterSlice.ts +16 -0
- package/frontend/template/src/features/counter/model/selectors.ts +4 -0
- package/frontend/template/src/features/counter/ui/CounterWidget.tsx +16 -0
- package/frontend/template/src/features/home/index.ts +1 -0
- package/frontend/template/src/features/home/routes.tsx +8 -0
- package/frontend/template/src/features/home/ui/HomePage.test.tsx +11 -0
- package/frontend/template/src/features/home/ui/HomePage.tsx +13 -0
- package/frontend/template/src/shared/api/baseApi.ts +9 -0
- package/frontend/template/src/shared/api/index.ts +1 -0
- package/frontend/template/src/shared/config/env.ts +3 -0
- package/frontend/template/src/shared/config/index.ts +1 -0
- package/frontend/template/src/shared/ui/Button.tsx +6 -0
- package/frontend/template/src/shared/ui/StatusPanel.test.tsx +25 -0
- package/frontend/template/src/shared/ui/StatusPanel.tsx +36 -0
- package/frontend/template/src/shared/ui/index.ts +4 -0
- package/frontend/template/src/shared/ui/styles.css +27 -0
- package/frontend/template/src/vite-env.d.ts +1 -0
- package/frontend/template/tests/setup.ts +1 -0
- package/frontend/template/tsconfig.json +21 -0
- package/frontend/template/vite.config.ts +73 -0
- package/npm/cli.js +53 -0
- package/package.json +30 -4
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Feature Blueprint — One House, One Public Door
|
|
2
|
+
|
|
3
|
+
Follow this when introducing or changing a feature. This document instantiates the supplied architecture, not a second architecture.
|
|
4
|
+
|
|
5
|
+
## Minimal layout
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
src/features/cart/
|
|
9
|
+
index.ts
|
|
10
|
+
routes.tsx
|
|
11
|
+
types.ts
|
|
12
|
+
ui/CartPage.tsx
|
|
13
|
+
ui/CartBadge.tsx
|
|
14
|
+
model/cartSlice.ts
|
|
15
|
+
model/selectors.ts
|
|
16
|
+
api/cartApi.ts
|
|
17
|
+
lib/calcTotal.ts
|
|
18
|
+
lib/calcTotal.test.ts
|
|
19
|
+
model/cartSlice.test.ts
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
**Do not create unnecessary directories.** A tiny feature may be only `ui/` plus `index.ts`. Place its tests beside the files being tested.
|
|
23
|
+
|
|
24
|
+
## 1. Public door first
|
|
25
|
+
|
|
26
|
+
The public contract controls what external modules can use:
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
// features/cart/index.ts
|
|
30
|
+
export { cartRoutes } from './routes'
|
|
31
|
+
export { CartBadge } from './ui/CartBadge'
|
|
32
|
+
export { cartReducer } from './model/cartSlice'
|
|
33
|
+
export { selectCartCount } from './model/selectors'
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Do not export internal-only pieces just to work around an import error. Agree the contract at task planning; expand it only when a consumer actually needs it.
|
|
37
|
+
|
|
38
|
+
## 2. UI owns presentation; model owns client state
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
// features/cart/model/selectors.ts
|
|
42
|
+
import type { CartState } from './cartSlice'
|
|
43
|
+
type WithCart = { cart: CartState }
|
|
44
|
+
export const selectCartCount = (state: WithCart) => state.cart.lines.length
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
// features/cart/ui/CartBadge.tsx
|
|
49
|
+
import { useSelector } from 'react-redux'
|
|
50
|
+
import { selectCartCount } from '../model/selectors'
|
|
51
|
+
export function CartBadge() {
|
|
52
|
+
const count = useSelector(selectCartCount)
|
|
53
|
+
return <span>{count}</span>
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- UI may import local model, helpers and API hooks.
|
|
58
|
+
- Model may not import local UI, app store or another feature's private files.
|
|
59
|
+
- Action, selector and slice exports are public only when included in this feature's door.
|
|
60
|
+
- The slice's `name: 'cart'` agrees with the store's `cart: cartReducer` key.
|
|
61
|
+
|
|
62
|
+
## 3. Routes are owned by the feature
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
// features/cart/routes.tsx
|
|
66
|
+
import type { RouteObject } from 'react-router'
|
|
67
|
+
export const cartRoutes: RouteObject[] = [
|
|
68
|
+
{
|
|
69
|
+
path: 'cart',
|
|
70
|
+
lazy: () => import('./ui/CartPage').then(m => ({ Component: m.CartPage })),
|
|
71
|
+
},
|
|
72
|
+
]
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
```tsx
|
|
76
|
+
// app/router.tsx — wiring, not page ownership
|
|
77
|
+
import { createBrowserRouter } from 'react-router'
|
|
78
|
+
import { cartRoutes } from '@/features/cart'
|
|
79
|
+
import { RootLayout } from './RootLayout'
|
|
80
|
+
export const router = createBrowserRouter([
|
|
81
|
+
{ path: '/', element: <RootLayout />, children: [...cartRoutes] },
|
|
82
|
+
])
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Root layout uses React Router's `<Outlet />`. Feature pages should be lazy-loaded. `app/router.tsx` never deep-imports a page.
|
|
86
|
+
|
|
87
|
+
## 4. Separate server data from browser state
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
// shared/api/baseApi.ts — no business endpoints or tags
|
|
91
|
+
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
|
|
92
|
+
import { env } from '@/shared/config'
|
|
93
|
+
export const baseApi = createApi({
|
|
94
|
+
reducerPath: 'api',
|
|
95
|
+
baseQuery: fetchBaseQuery({ baseUrl: env.apiUrl }),
|
|
96
|
+
endpoints: () => ({}),
|
|
97
|
+
})
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
// features/cart/api/cartApi.ts
|
|
102
|
+
import { baseApi } from '@/shared/api'
|
|
103
|
+
import type { CartLine } from '../types'
|
|
104
|
+
const api = baseApi.enhanceEndpoints({ addTagTypes: ['Cart'] })
|
|
105
|
+
export const cartApi = api.injectEndpoints({
|
|
106
|
+
endpoints: build => ({
|
|
107
|
+
getCart: build.query<CartLine[], void>({
|
|
108
|
+
query: () => 'cart',
|
|
109
|
+
providesTags: ['Cart'],
|
|
110
|
+
}),
|
|
111
|
+
addToCart: build.mutation<void, CartLine>({
|
|
112
|
+
query: line => ({ url: 'cart', method: 'POST', body: line }),
|
|
113
|
+
invalidatesTags: ['Cart'],
|
|
114
|
+
}),
|
|
115
|
+
}),
|
|
116
|
+
})
|
|
117
|
+
export const { useGetCartQuery, useAddToCartMutation } = cartApi
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- One base reducer/middleware connection in `app/store.ts`.
|
|
121
|
+
- No business endpoints/tags in `shared/api/baseApi.ts`.
|
|
122
|
+
- Do not duplicate `getCart` results into a cart slice.
|
|
123
|
+
- Server data uses RTK Query cache; browser/client state uses the feature model when shared/Redux state is needed.
|
|
124
|
+
|
|
125
|
+
## 5. Generic shared components receive props
|
|
126
|
+
|
|
127
|
+
```tsx
|
|
128
|
+
// shared/ui/Card.tsx — generic
|
|
129
|
+
export function Card({ title, children }: {
|
|
130
|
+
title: string
|
|
131
|
+
children?: React.ReactNode
|
|
132
|
+
}) {
|
|
133
|
+
return <section><h3>{title}</h3>{children}</section>
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
A `ProductCard` belongs in `features/products/ui/`, even if it wraps `shared/ui/Card`. A shared Card cannot import product selectors or calculate cart totals.
|
|
138
|
+
|
|
139
|
+
## 6. Tests next to the modules
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
// features/cart/lib/calcTotal.test.ts
|
|
143
|
+
import { describe, expect, it } from 'vite-plus/test'
|
|
144
|
+
import { calcTotal } from './calcTotal'
|
|
145
|
+
|
|
146
|
+
describe('calcTotal', () => {
|
|
147
|
+
it('returns zero for an empty collection', () => {
|
|
148
|
+
expect(calcTotal([])).toBe(0)
|
|
149
|
+
})
|
|
150
|
+
})
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Examples are structural blueprints. Verify types and runtime compatibility against the **actual** target repository before using them verbatim.
|
|
154
|
+
|
|
155
|
+
## Feature creation checklist
|
|
156
|
+
|
|
157
|
+
- [ ] Capability has one clear owner and a bounded module scope.
|
|
158
|
+
- [ ] `index.ts` public API/types are explicitly defined.
|
|
159
|
+
- [ ] Only needed rooms created; UI/model/API/lib ownership is correct.
|
|
160
|
+
- [ ] Any cross-feature import uses the other feature's door, and the graph is acyclic.
|
|
161
|
+
- [ ] Routes are feature-owned, root-composed and lazy.
|
|
162
|
+
- [ ] State is not copied between RTK Query cache and Redux slices.
|
|
163
|
+
- [ ] Tests are adjacent to modules and cover expected behavior/edge cases.
|
|
164
|
+
- [ ] `node scripts/check-architecture.mjs`, `vp check`, `vp test`, `vp build` pass and diff has no surprises.
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Frontend Architecture — Normative Rules
|
|
2
|
+
|
|
3
|
+
**Source:** supplied course *Front-end structure: React, Router, Redux on Vite+*, chapters 1–10 and reference pages 65–66.
|
|
4
|
+
|
|
5
|
+
**Goal:** independently add, debug and remove a user-facing capability without allowing unrelated modules to break. All rules in this document apply to agent-written, human-written, new and edited code.
|
|
6
|
+
|
|
7
|
+
## 1. The three zones
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
flowchart TD
|
|
11
|
+
APP["src/app — wiring only"] --> F1["src/features/auth"]
|
|
12
|
+
APP --> F2["src/features/cart"]
|
|
13
|
+
APP --> SH["src/shared — generic base"]
|
|
14
|
+
F1 --> SH
|
|
15
|
+
F2 --> SH
|
|
16
|
+
F2 -->|"public index.ts only"| F1
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
| Zone | Allowed responsibility | Forbidden |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `src/app/` | Bootstrap, providers, root layout, router composition, reducer/middleware composition | Feature API calls, business calculations, business forms, owning feature state |
|
|
22
|
+
| `src/features/<name>/` | Exactly one business capability, its UI, state, endpoints, route definitions, helpers, types and tests | Import from app; deep-import another feature; unbounded cross-feature coupling |
|
|
23
|
+
| `src/shared/` | Business-agnostic UI, utilities, HTTP/API transport, configuration | Knowledge of users, cart, products, courses or any feature; importing app/features; selecting business store state |
|
|
24
|
+
|
|
25
|
+
Expected tree (create only needed rooms):
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
src/
|
|
29
|
+
app/
|
|
30
|
+
main.tsx
|
|
31
|
+
providers.tsx
|
|
32
|
+
store.ts
|
|
33
|
+
router.tsx
|
|
34
|
+
RootLayout.tsx
|
|
35
|
+
features/
|
|
36
|
+
<name>/
|
|
37
|
+
index.ts # public door
|
|
38
|
+
routes.tsx # feature-owned route list
|
|
39
|
+
types.ts # feature data contract
|
|
40
|
+
ui/ # views and components
|
|
41
|
+
model/ # Redux slice/selectors
|
|
42
|
+
api/ # RTK Query injected endpoints
|
|
43
|
+
lib/ # feature-only helpers
|
|
44
|
+
# *.test.ts(x) live beside tested source
|
|
45
|
+
shared/
|
|
46
|
+
ui/index.ts
|
|
47
|
+
lib/index.ts
|
|
48
|
+
api/index.ts
|
|
49
|
+
api/baseApi.ts
|
|
50
|
+
config/index.ts
|
|
51
|
+
config/env.ts
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## 2. Hard rules and failure examples
|
|
55
|
+
|
|
56
|
+
### A. Dependencies only point down
|
|
57
|
+
|
|
58
|
+
- `app -> features`, `app -> shared`, `features -> shared`: **allowed**.
|
|
59
|
+
- `features -> app`, `shared -> features`, `shared -> app`: **FAIL**.
|
|
60
|
+
- Type imports, `export ... from`, and literal dynamic imports follow the same rules.
|
|
61
|
+
- External library imports are allowed in the appropriate zone.
|
|
62
|
+
|
|
63
|
+
### B. Another feature is accessible only through its public door
|
|
64
|
+
|
|
65
|
+
- **PASS**: `import { selectUser } from '@/features/auth'` in `features/cart`.
|
|
66
|
+
- **FAIL**: `import { selectUser } from '@/features/auth/model/selectors'`.
|
|
67
|
+
- **FAIL**: `import { selectUser } from '../../auth/model/selectors'`.
|
|
68
|
+
- `src/app` is an external consumer and must use the same door.
|
|
69
|
+
- Inside the **same** feature, import private modules relatively, such as `../model/selectors`.
|
|
70
|
+
- Shared sections expose `@/shared/ui`, `@/shared/lib`, `@/shared/api`, `@/shared/config`; external consumers must not deep-import their internals.
|
|
71
|
+
|
|
72
|
+
### C. No import cycles
|
|
73
|
+
|
|
74
|
+
- If `cart` depends on `auth`, `auth` must not depend on `cart`.
|
|
75
|
+
- Reject direct and indirect cycles. A type-only cycle is treated as an architecture failure in this pack even where a particular linter may ignore it.
|
|
76
|
+
- Resolve cycles by removing reverse knowledge, using an existing public interface, or keeping orchestration in `app/`; never create an illicit central business hub in `shared/`.
|
|
77
|
+
|
|
78
|
+
### D. Internal direction
|
|
79
|
+
|
|
80
|
+
- UI may read model; model may not import UI.
|
|
81
|
+
- Keep independent helpers in `lib/`, data shapes in `types.ts` when needed, and API endpoints in `api/`.
|
|
82
|
+
- Do not reach outside a feature with relative traversal; use the source alias `@/`.
|
|
83
|
+
- Do not add rooms just for symmetry: small features may contain only `ui/` and `index.ts`.
|
|
84
|
+
|
|
85
|
+
### E. Shared admission: both tests must pass
|
|
86
|
+
|
|
87
|
+
1. **Copy test:** Could the code be dropped unchanged into an unrelated blog/game application?
|
|
88
|
+
2. **Rule of two:** Does a second feature actually need the generic capability now?
|
|
89
|
+
|
|
90
|
+
If either answer is no, leave the item inside its feature. A `Card` that accepts generic props may qualify; `ProductCard` or `UserAvatar` still names a business concept and belongs to its owner feature even if reused elsewhere. Shared UI is fed through props; it must not import feature selectors.
|
|
91
|
+
|
|
92
|
+
## 3. Routes and code splitting
|
|
93
|
+
|
|
94
|
+
- Each feature owns `features/<name>/routes.tsx` and exports the route array via `features/<name>/index.ts`.
|
|
95
|
+
- A feature route's child path is relative to the root layout (for example `cart`, not `/cart`).
|
|
96
|
+
- Prefer `lazy: () => import('./ui/CartPage').then(m => ({ Component: m.CartPage }))` for page modules.
|
|
97
|
+
- `app/router.tsx` imports `authRoutes`, `cartRoutes`, etc. through their respective public doors and spreads lists under `RootLayout` with `<Outlet />`.
|
|
98
|
+
- `app/RootLayout.tsx` may compose feature-exposed widgets; widgets containing business semantics remain in their feature.
|
|
99
|
+
|
|
100
|
+
## 4. State ownership and consistency
|
|
101
|
+
|
|
102
|
+
- Browser/client state belongs to the feature Redux Toolkit slice in `model/`: for example menu-open state, in-progress filter state and draft forms where Redux is appropriate. Small purely local UI state may remain component-local; do not force ephemeral input state into a global slice.
|
|
103
|
+
- Each feature's slice **name** must match its configured reducer key in `app/store.ts`.
|
|
104
|
+
- Feature selectors must rely on a minimal state shape (`{ cart: CartState }`) rather than importing `RootState` from app.
|
|
105
|
+
- Multiple features may communicate via exported actions/selectors from a feature's door, without creating reverse imports or circular dependencies.
|
|
106
|
+
- Feature-server records live in the RTK Query cache; do **not** duplicate them into a Redux slice that becomes a second source of truth.
|
|
107
|
+
|
|
108
|
+
## 5. API ownership
|
|
109
|
+
|
|
110
|
+
- `shared/api/baseApi.ts`: a single empty RTK Query base transport with generic base URL/config; **no business endpoints or tag names**.
|
|
111
|
+
- `features/<name>/api/`: feature-specific `injectEndpoints` definitions, queries, mutations, and feature-specific tag names.
|
|
112
|
+
- `app/store.ts`: installs the base API reducer and middleware once.
|
|
113
|
+
- Generic network configuration should read `VITE_` variables centrally through `shared/config/env.ts` rather than scattered `import.meta.env` usage.
|
|
114
|
+
|
|
115
|
+
## 6. Architecture preservation / deletion audit
|
|
116
|
+
|
|
117
|
+
The important property is **removability**: removing a feature should require removing its `app` wiring, not changing `shared/` or unrelated feature internals. To check:
|
|
118
|
+
|
|
119
|
+
1. Run `node scripts/check-architecture.mjs` to audit incoming dependencies and cycles; it will flag illegal cross-zone/door imports.
|
|
120
|
+
2. Review feature exports and dependencies using a dependency graph or `git grep`.
|
|
121
|
+
3. If a literal deletion smoke test is needed, do so in a **temporary clean copy/worktree**, never in the active working tree. Remove only the chosen feature, disable its app wiring, then run type checks. Fail if other non-app modules unexpectedly need edits.
|
|
122
|
+
4. Restore/dispose of the temporary copy, leaving the user's working tree intact.
|
|
123
|
+
|
|
124
|
+
Caveat: the source course simplifies the deletion test. **Legal** dependencies on a feature's public API from another feature still create required downstream edits if the feature is removed. The strict audit should therefore record these public dependencies explicitly, and a deletion claim may only be made when consumers have been considered; do not falsely promise unconditional removable-by-folder behavior.
|
|
125
|
+
|
|
126
|
+
## 7. Decisions and exceptions
|
|
127
|
+
|
|
128
|
+
- Do not silently use a different architecture (e.g., one giant `components/`, central `services/` containing business endpoints, global `RootState` imports, or UI-specific logic under shared).
|
|
129
|
+
- A documented user-approved exception must explain the rule, reason, affected files, migration plan, and tests; the exception is not a hidden linter disable.
|
|
130
|
+
- New cross-feature dependencies require a public API review and an explicit cycle check.
|
|
131
|
+
|
|
132
|
+
These structural rules are **normative**. Consult `docs/TESTING_AND_GATES.md` for executable and manual verification.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Dependency security and frontend security baseline
|
|
2
|
+
|
|
3
|
+
## What dependency monitoring does
|
|
4
|
+
Every npm package can bring many transitive dependencies. A vulnerability in any of them can affect the project even if you did not import it directly. `npm audit` compares the lockfile dependency graph to registry advisories; it can miss unknown vulnerabilities and does not replace review.
|
|
5
|
+
|
|
6
|
+
## OBSESSION controls
|
|
7
|
+
1. Commit `package-lock.json` created by the first `npm install` and use `npm ci` in CI for deterministic installs. Avoid floating dependency ranges on production deployment unless lockfile controls them.
|
|
8
|
+
2. Run `npm run security:audit` (`npm audit --audit-level=high`) during verification. High/critical known vulnerabilities fail the check; lower severities still require review.
|
|
9
|
+
3. `.github/dependabot.yml` checks npm and GitHub Actions updates weekly. Enable Dependabot alerts/security updates in GitHub repository settings; the YAML alone does not enable all alert settings.
|
|
10
|
+
4. Review update PRs, changelogs, removed features, package maintainers and CI status. Do not run `npm audit fix --force` blindly; it can make breaking changes.
|
|
11
|
+
5. Prefer standard, well-maintained packages. Require approval before new runtime dependencies or network SDKs.
|
|
12
|
+
6. Keep automated CI permission scopes minimal (`contents: read` by default) and protect the main branch via required checks and reviews.
|
|
13
|
+
7. Turn on repository secret scanning, push protection and branch protection when supported by your GitHub plan/organisation.
|
|
14
|
+
|
|
15
|
+
## Browser code security rules
|
|
16
|
+
- Anything beginning with `VITE_` is bundled into client code. Never store private API keys, signing secrets, database passwords or service tokens there. `.env` being Git-ignored **does not** make `VITE_` variables private.
|
|
17
|
+
- Authentication and authorization decisions must be verified by the backend. Hiding a React route is not an authorization boundary.
|
|
18
|
+
- Avoid raw HTML rendering (`dangerouslySetInnerHTML`). If genuine rich HTML is required, sanitize it with an approved library and test the content boundaries.
|
|
19
|
+
- Validate all URL parameters and server responses. TypeScript types do not validate runtime responses.
|
|
20
|
+
- Prefer secure, HttpOnly, SameSite cookies for session credentials when appropriate to the backend design, with CSRF protections for cookie-authenticated mutations. Never expose authentication secrets to logs.
|
|
21
|
+
- Use HTTPS in production, define an appropriate Content Security Policy at the hosting/proxy layer, and configure cookie/CORS/security headers server-side.
|
|
22
|
+
- Do not upload production user data or secrets to CI logs, screenshots, browser traces or issue attachments.
|
|
23
|
+
|
|
24
|
+
## Workflow for vulnerabilities
|
|
25
|
+
1. Determine affected package and whether it is runtime or dev-only.
|
|
26
|
+
2. Check the advisory for exploitability and a patched version.
|
|
27
|
+
3. Update the smallest compatible dependency range, regenerate lockfile, run tests/build/E2E.
|
|
28
|
+
4. Document any high/critical exception, with approval and an expiry date; do not silently suppress `npm audit` results.
|
|
29
|
+
5. Audit continuously: new advisories can arrive without source changes.
|
|
30
|
+
|
|
31
|
+
## Threat model caveat
|
|
32
|
+
The frontend can reduce exposure but cannot guarantee protection of APIs or user records. Real access control, input validation and storage permissions must be enforced server-side.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# State ownership decision tree (mandatory)
|
|
2
|
+
|
|
3
|
+
This supplements the original server-state versus browser-state distinction.
|
|
4
|
+
|
|
5
|
+
## Ask these questions, in order
|
|
6
|
+
|
|
7
|
+
1. **Does the server own the record?** Use RTK Query (`features/<x>/api/`) for read/write, caching, invalidation, loading and error metadata. Do not copy results into a Redux slice. Example: enrolments fetched from `/api/enrolments`.
|
|
8
|
+
2. **Must a user be able to bookmark/share/back-forward/refresh the choice?** Use React Router search or route params. Example: `?category=english&page=2`; parse, validate and default URL values.
|
|
9
|
+
3. **Does only one component or short-lived subtree need it?** Use React `useState` or `useReducer`. Example: modal open, form field, password reveal. For complex local transitions, use local `useReducer`.
|
|
10
|
+
4. **Does several feature UI modules or routes need the same client-owned workflow state?** Consider a feature Redux Toolkit slice in `model/`; use selectors scoped to that feature. Example: an unsaved multi-step enrolment draft that spans routes.
|
|
11
|
+
5. **Is it derivable from existing data?** Compute it with a selector or render-time expression instead of storing a duplicate. Example: cart total = sum of lines.
|
|
12
|
+
|
|
13
|
+
## Ownership examples
|
|
14
|
+
|
|
15
|
+
| Data | Owner | Why |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| Open filter drawer | component `useState` | only local UI |
|
|
18
|
+
| Selected course category & page | URL search params | shareable and browser-back friendly |
|
|
19
|
+
| Course results and loading | feature RTK Query endpoint | server owns course data |
|
|
20
|
+
| Request error/retry | RTK Query metadata + feature UI | source of truth is request result |
|
|
21
|
+
| Multi-step unsaved learner enrolment | feature Redux slice | shared client workflow across screens |
|
|
22
|
+
| User profile from API | feature RTK Query | do not duplicate in Redux |
|
|
23
|
+
| Calculated number of selected courses | derived selector | not independent state |
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- URL inputs are untrusted. Parse numbers, check allowed sort values, and enforce valid pagination.
|
|
28
|
+
- Do not persist sensitive data in the URL, localStorage or Redux persist; never expose auth tokens in browser-accessible stores without a threat-model decision.
|
|
29
|
+
- URL state is for navigation semantics, not secrets. Avoid putting personally identifying details in query strings.
|
|
30
|
+
- RTK Query `isLoading`/`isFetching`, `isError`, `data` guide the UI states in `docs/UI_STATES.md`.
|
|
31
|
+
- Prefer typed props over global state. Shared UI never reads feature Redux selectors.
|
|
32
|
+
- Keep a feature's server endpoints and slice private except explicitly exported stable public APIs.
|
|
33
|
+
- If a value is cached server data, it remains in RTK Query; `useState` may hold only a draft edit until saved.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Chapter 9 - Strict Agent Task Protocol
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
Ensure Claude Code (VS Code) never treats a broadly worded ticket as permission to rewrite the frontend architecture.
|
|
5
|
+
|
|
6
|
+
## Before each coding task
|
|
7
|
+
|
|
8
|
+
1. Read `CLAUDE.md`, `AGENTS.md`, and all linked architecture/testing files.
|
|
9
|
+
2. Read the task and acceptance criteria. Ask targeted clarifying questions only where required to avoid a wrong change. Do not invent requirements.
|
|
10
|
+
3. Inspect existing functionality and relevant tests; record current Git worktree state, including untracked files.
|
|
11
|
+
4. Declare a **scope contract**, receive approval, and start the task manifest with `npm run scope:start -- --id OB-123 --allow "src/features/example/**"` before editing. See `docs/TASK_SCOPE.md`. Use this template:
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
Task / ticket: <identifier or description>
|
|
15
|
+
Desired observable result: <behavior>
|
|
16
|
+
Acceptance criteria: <testable statements>
|
|
17
|
+
Main feature: src/features/<name>
|
|
18
|
+
Allowed paths: <precise files or room>
|
|
19
|
+
Permitted wiring: src/app/router.tsx or src/app/store.ts (only if required)
|
|
20
|
+
Explicitly forbidden changes: other features, shared, root configs unless approved
|
|
21
|
+
Testing plan: <tests to create/run>
|
|
22
|
+
Baseline checks: <results or unavailable>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
5. For new features, design `types.ts` and `index.ts` public contract first, then implement one room at a time. If a changed contract impacts consumers, request approval before broad edits.
|
|
26
|
+
|
|
27
|
+
## During the task
|
|
28
|
+
|
|
29
|
+
- Prefer the smallest change that meets acceptance criteria.
|
|
30
|
+
- Do not bypass another feature's `index.ts`.
|
|
31
|
+
- Do not duplicate RTK Query server data into feature slices.
|
|
32
|
+
- Avoid any new dependency, root config change or `shared/` addition without explicit justification and approval.
|
|
33
|
+
- Preserve unrelated user modifications. Never use destructive global restore or clean commands.
|
|
34
|
+
- Add or update a colocated test beside each changed business module where appropriate.
|
|
35
|
+
|
|
36
|
+
## After the task - required final recheck
|
|
37
|
+
|
|
38
|
+
1. `npm run guard`: boundaries and import cycles.
|
|
39
|
+
2. `npm run guard:test`: verify guard actually rejects known forbidden structures.
|
|
40
|
+
3. `npm exec -- vp check`: format, lint, type checks.
|
|
41
|
+
4. `npm exec -- vp test`: behavioral tests.
|
|
42
|
+
5. `npm exec -- vp build`: production build.
|
|
43
|
+
6. `npm run scope:check` (must PASS for every coding task) and `git status --short`, `git diff --stat`, `git diff`, plus review each untracked file.
|
|
44
|
+
7. Re-evaluate Rules A-H, shared copy test, rule-of-two, and relevant acceptance criteria manually.
|
|
45
|
+
8. Report exact status per gate: PASS (ran and passed), FAIL (ran and failed), BLOCKED (not executable), or N/A (only when genuinely inapplicable).
|
|
46
|
+
|
|
47
|
+
Never report overall PASS while required checks are failing or unrun. CI is a separate final safeguard; passing local checks is not equivalent to CI being green.
|
|
48
|
+
|
|
49
|
+
## Completion command
|
|
50
|
+
Run `npm run verify:task` after completing real development tasks. The plain `npm run verify` is for baseline/CI verification and does not assert a task scope.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Agent task-scope manifest and validation
|
|
2
|
+
|
|
3
|
+
## Intended guarantee
|
|
4
|
+
Detect files that were created, modified or deleted outside the approved task paths **since the scope was started**. It prevents accidental agent drift, including changes to existing uncommitted files. It is not a security sandbox or cryptographic guarantee.
|
|
5
|
+
|
|
6
|
+
## Before the first edit
|
|
7
|
+
1. Read the Jira task or user request and agree acceptance criteria.
|
|
8
|
+
2. Record currently uncommitted/user changes and do not alter them.
|
|
9
|
+
3. Make a precise list of allowed files/rooms. The agent must ask permission to add a different feature or root config.
|
|
10
|
+
4. Run from the project root, *before making code changes*:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm run scope:start -- --id OB-123 --allow "src/features/home/**" --allow "src/app/router.tsx"
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The command writes `.agent/task-scope.json`, storing file hashes at the moment the task begins. Git ignores this local file. Use exact paths or `room/**`; broad `**`, `src/**` and `src/features/**` patterns are rejected. You cannot start a second task while one manifest exists.
|
|
17
|
+
|
|
18
|
+
## Before claiming completion
|
|
19
|
+
```sh
|
|
20
|
+
npm run verify:task
|
|
21
|
+
# or individually:
|
|
22
|
+
npm run scope:check
|
|
23
|
+
npm run verify
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
`scope:check` compares hashes of each project file with the initial snapshot, reports created/modified/deleted paths and fails if any are out of scope. It fails closed when a manifest is missing.
|
|
27
|
+
|
|
28
|
+
## After review
|
|
29
|
+
Preserve the task's compliance report with the Jira issue / PR. You may remove `.agent/task-scope.json` **only after** the task is completed and reviewed, to begin the next task. Never erase it to silence an error.
|
|
30
|
+
|
|
31
|
+
## Limits and escalation
|
|
32
|
+
- An LLM that can edit the working tree may also alter this local manifest or guard code; this is a **tripwire**, not a tamper-proof permission system. Use human review, Git protected branches and CI for stronger controls.
|
|
33
|
+
- The script intentionally does not inspect ignored package caches, build outputs or `.env` files. Review sensitive config separately.
|
|
34
|
+
- CI executes the architecture, unit, browser and audit gates; local task scope remains a per-developer gate, not a required CI check (manifest is ignored). For stricter organizational enforcement, commit per-PR allowlists and verify against the PR base commit on CI.
|
|
35
|
+
- Changes to `package.json`, lockfiles, CI or lint rules require specific permission and explicitly listed paths.
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Technology Stack and Configuration Contract
|
|
2
|
+
|
|
3
|
+
The supplied architecture chooses these technologies. Do not silently swap them.
|
|
4
|
+
|
|
5
|
+
| Category | Technology | Rule |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| Language | TypeScript + TSX | Keep contracts typed; avoid untyped escape hatches |
|
|
8
|
+
| UI | React | UI resides in feature `ui/`; generic primitives in `shared/ui` |
|
|
9
|
+
| Routing | React Router | Feature-owned route objects, app-level composition and lazy pages |
|
|
10
|
+
| Client shared state | Redux Toolkit + React Redux | One feature-owned slice/selectors set per capability |
|
|
11
|
+
| Server state | RTK Query | One generic base API, injected endpoints owned by features |
|
|
12
|
+
| Toolchain | Vite+ | Use `vp` commands; Vite+ config in `vite.config.ts` |
|
|
13
|
+
| Unit tests | Vite+ test runner (`vite-plus/test`) | Colocate `*.test.ts(x)` with code |
|
|
14
|
+
| Static checks | Vite+ `vp check` | Formatting + lint + type check (type checking must be enabled) |
|
|
15
|
+
| Module alias | `@/` -> `src/` | Resolve in both TypeScript and Vite+ |
|
|
16
|
+
|
|
17
|
+
**No precise package versions were present in the blueprint.** Inspect `package.json`, lockfile and actual `vp toolchain` output before editing config. Do not assume an API is supported based solely on a copied example.
|
|
18
|
+
|
|
19
|
+
## Required command gates
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
node scripts/check-architecture.mjs
|
|
23
|
+
vp check
|
|
24
|
+
vp test
|
|
25
|
+
vp build
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
For iterative development:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
vp dev
|
|
32
|
+
vp test watch
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The original course requires `vp check` and `vp test` for every completed room; this rules pack additionally requires the architecture checker and a full build at task completion.
|
|
36
|
+
|
|
37
|
+
## Source alias (illustrative, merge with existing config)
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
// tsconfig.json (shown as an example; remove this comment in real JSON)
|
|
41
|
+
{
|
|
42
|
+
"compilerOptions": {
|
|
43
|
+
"paths": { "@/*": ["./src/*"] }
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
// vite.config.ts (merge with existing config)
|
|
50
|
+
import { fileURLToPath } from 'node:url'
|
|
51
|
+
import { defineConfig } from 'vite-plus'
|
|
52
|
+
import react from '@vitejs/plugin-react'
|
|
53
|
+
|
|
54
|
+
export default defineConfig({
|
|
55
|
+
plugins: [react()],
|
|
56
|
+
resolve: {
|
|
57
|
+
alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
|
|
58
|
+
},
|
|
59
|
+
lint: {
|
|
60
|
+
options: { typeAware: true, typeCheck: true },
|
|
61
|
+
// Add import boundary rules and cycle guard supported by
|
|
62
|
+
// the installed Oxlint/Vite+ versions.
|
|
63
|
+
},
|
|
64
|
+
test: { include: ['src/**/*.test.{ts,tsx}'] },
|
|
65
|
+
})
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**Important:** Do not overwrite the existing `tsconfig.json` or `vite.config.ts` with this fragment. Add these settings to the project’s real configuration, preserving required existing settings. Vite+ `vp check` only covers type checks when the required type-aware options are active. A plain successful command without configured type checks is not proof of a type-safe frontend.
|
|
69
|
+
|
|
70
|
+
## Enforcing rules A/B/C
|
|
71
|
+
|
|
72
|
+
1. Run `node scripts/check-architecture.mjs` after every module change and in CI. This bundled checker enforces relevant import and placement restrictions even if lint configuration differs.
|
|
73
|
+
2. Configure **Oxlint** via Vite+'s supported `lint` configuration to reject upward imports, feature deep imports and import cycles. Ensure it checks `src/**/*.ts(x)` and tests too.
|
|
74
|
+
3. The source course sketches `no-restricted-imports` and `import/no-cycle` configuration inside `vite.config.ts`. Treat that example as a **design specification**, not proof that its exact syntax is compatible with every installed version.
|
|
75
|
+
4. Run a negative-control test: intentionally introduce one upward import and confirm `node scripts/check-architecture.mjs` returns nonzero; then clean up **only your own test fixture**. Do not mutate production files to test the guard.
|
|
76
|
+
5. Version and configuration changes to these guards require explicit review: do not disable rules or add broad ignore patterns to make a change pass.
|
|
77
|
+
|
|
78
|
+
Official Vite+ references (consult when configuring the *actual* repository):
|
|
79
|
+
|
|
80
|
+
- https://viteplus.dev/guide/check
|
|
81
|
+
- https://viteplus.dev/guide/test
|
|
82
|
+
- https://viteplus.dev/config/lint
|
|
83
|
+
- https://viteplus.dev/config/
|
|
84
|
+
|
|
85
|
+
## CI requirements
|
|
86
|
+
|
|
87
|
+
CI must install dependencies using the project's existing package manager/lockfile and execute, in order:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
node scripts/check-architecture.mjs
|
|
91
|
+
vp check
|
|
92
|
+
vp test
|
|
93
|
+
vp build
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Require all commands to succeed before merging frontend changes. Do not call a task CI-enforced until the target repository actually has this CI wired into branch protection or merge policy.
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Strict Architecture and Quality Gates
|
|
2
|
+
|
|
3
|
+
A coding task is **PASS** only when every applicable mandatory gate was executed successfully, verified against the changed code, and reported. Running only `vp check` is not enough: the blueprint explicitly distinguishes structural checking from correct behavior.
|
|
4
|
+
|
|
5
|
+
For the current Vite+ / Oxlint rule implementation and agent task-scope procedure, see `CHAPTER_8_9_10_ENFORCEMENT.md` and `TASK_PROTOCOL.md`.
|
|
6
|
+
|
|
7
|
+
## Mandatory gates for every coding task
|
|
8
|
+
|
|
9
|
+
| Gate | Test | Pass criterion | Failure action |
|
|
10
|
+
|---|---|---|---|
|
|
11
|
+
| G00 | Read rules + inspect current repo | Docs read, real stack/config examined | Stop before editing |
|
|
12
|
+
| G01 | Allowed change scope | Every changed path is within plan or explicitly approved wiring | Revert **only unintended own changes** or request approval |
|
|
13
|
+
| G02 | Structural checker | `node scripts/check-architecture.mjs` exits 0 | Fix all A/B/C/placement failures |
|
|
14
|
+
| G03 | Format/lint/types | `vp check` exits 0 with type checking enabled | Fix, or mark BLOCKED if tool/config unavailable |
|
|
15
|
+
| G04 | Behavioral tests | `vp test` exits 0; focused changed tests exist | Fix behavior/tests; do not weaken assertions |
|
|
16
|
+
| G05 | Production build | `vp build` exits 0 | Fix build; report baseline separately |
|
|
17
|
+
| G06 | Diff audit | `git status --short`, `git diff --stat`, `git diff` reviewed | Investigate unplanned, generated or secret changes |
|
|
18
|
+
| G07 | Manual architecture audit | Explicitly re-evaluate all rules A–H below | Do not mark PASS if any rule unverified |
|
|
19
|
+
| G08 | Regression/contract audit | Public API, routes, state/API behavior, affected consumers reviewed | Add tests; correct impact |
|
|
20
|
+
| G09 | Completion evidence | Final report contains commands, results, changed files, status | Mark incomplete until reported |
|
|
21
|
+
|
|
22
|
+
For documentation-only edits, still run G00/G01/G02/G06/G09; the agent must state which executable gates are not applicable and why. For frontend code changes, G00–G09 are required. If dependencies cannot be installed or a CLI is absent, status is **BLOCKED**, never PASS.
|
|
23
|
+
|
|
24
|
+
## Manual architecture recheck on **every** task
|
|
25
|
+
|
|
26
|
+
| Rule | Exact audit question | Evidence required |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| A | Does any feature import app, or shared import feature/app, including types and indirect paths? | Checker result + spot review |
|
|
29
|
+
| B | Does every external feature consumer use only `@/features/<name>`? Does shared expose its section door? | Checker result + imports review |
|
|
30
|
+
| C | Is the module and cross-feature graph acyclic? | Checker result; lint graph where available |
|
|
31
|
+
| D | Is business logic absent from app and shared? Is model independent of UI? | Manual review + checker heuristics |
|
|
32
|
+
| E | Did each shared addition pass both copy test and rule of two? | State both concrete answers |
|
|
33
|
+
| F | Do features own routes, are pages lazy, and does app only compose? | Inspect changed `routes.tsx`, `router.tsx` |
|
|
34
|
+
| G | Are slice names/keys and selector shapes correct? Is server data never duplicated? | Inspect changed state and API paths |
|
|
35
|
+
| H | Do changed modules have colocated, meaningful tests? | Test filename and assertions reviewed |
|
|
36
|
+
|
|
37
|
+
A linter cannot prove genericity, business ownership, good test assertions, API correctness, state consistency, or real user behavior. These remain **manual review items** and must not be marked automated.
|
|
38
|
+
|
|
39
|
+
## Behavioral test expectations
|
|
40
|
+
|
|
41
|
+
For each changed capability, at minimum cover positive behavior, an important edge case, and a failure/error path where relevant. Add regression tests for repaired bugs. Apply specific checks based on the touched room:
|
|
42
|
+
|
|
43
|
+
- `lib/`: deterministic inputs, zero/empty, invalid/boundary conditions, calculations.
|
|
44
|
+
- `model/`: initial state, action transitions, selectors, feature integration (for example logout-clears-cart).
|
|
45
|
+
- `api/`: request/mutation definitions, loading/errors, cache invalidation and refetch expectations; mock network appropriately.
|
|
46
|
+
- `ui/`: user-visible interaction, conditional states, accessibility checks; use the project's approved UI test framework, not an unapproved stack change.
|
|
47
|
+
- `routes.tsx`: expected route, missing/invalid parameters, lazy-load and error-fallback behavior where relevant.
|
|
48
|
+
- `shared/`: independently reusable behavior and no business dependencies.
|
|
49
|
+
|
|
50
|
+
If the repository lacks the approved test tooling for UI/API integration, report the gap instead of claiming coverage you did not implement.
|
|
51
|
+
|
|
52
|
+
## Full recheck sequence
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# 1. Must always run in the repository root
|
|
56
|
+
node scripts/check-architecture.mjs
|
|
57
|
+
|
|
58
|
+
# 2. Only an actually configured Vite+ project can run the following
|
|
59
|
+
vp check
|
|
60
|
+
vp test
|
|
61
|
+
vp build
|
|
62
|
+
|
|
63
|
+
# 3. See what was touched
|
|
64
|
+
git status --short
|
|
65
|
+
git diff --stat
|
|
66
|
+
git diff
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Notes:
|
|
70
|
+
- `vp check` must be configured to actually perform type checks (`lint.options.typeAware` + `lint.options.typeCheck`).
|
|
71
|
+
- `vp test` is a one-shot test run; `vp test watch` is for interactive development, not a CI gate.
|
|
72
|
+
- For monorepos, run the commands in the correct frontend package context and record it.
|
|
73
|
+
- For a new rule/checker update, run `node --test scripts/check-architecture.test.mjs` and run the checker itself.
|
|
74
|
+
- Do not use `git restore .`, `git clean -fd`, or feature deletion as a shortcut in an unclean user's worktree.
|
|
75
|
+
|
|
76
|
+
## Negative controls (one-time on setup; repeat after checker changes)
|
|
77
|
+
|
|
78
|
+
Our bundled checker has a self-test suite that constructs disposable repositories and verifies:
|
|
79
|
+
|
|
80
|
+
1. Valid `app -> feature door -> shared` imports pass.
|
|
81
|
+
2. Feature importing `app` fails (Rule A).
|
|
82
|
+
3. Shared importing feature fails (Rule A).
|
|
83
|
+
4. Deep cross-feature import fails (Rule B).
|
|
84
|
+
5. Relative cross-feature import fails (Rule B).
|
|
85
|
+
6. Cross-feature and intra-feature cycles fail (Rule C).
|
|
86
|
+
7. `model -> ui` fails.
|
|
87
|
+
8. `shared/ui -> feature store` pattern fails.
|
|
88
|
+
9. A test without its adjacent source fails.
|
|
89
|
+
10. A valid feature test and public door pass.
|
|
90
|
+
|
|
91
|
+
**Run:** `node --test scripts/check-architecture.test.mjs`. All tests must pass after changes to checker/rules. The checker intentionally fails closed on missing `src/` and reports that the target project is not yet installed/structured.
|
|
92
|
+
|
|
93
|
+
## Failure handling and task status
|
|
94
|
+
|
|
95
|
+
- **PASS:** all applicable gates succeeded, compliance report contains evidence.
|
|
96
|
+
- **FAIL:** a gate ran and found a violation or implementation defect.
|
|
97
|
+
- **BLOCKED:** a required gate could not be run or verified (missing installed tool, unavailable network, absent project, insufficient permission).
|
|
98
|
+
- **N/A:** permitted only for a gate objectively unrelated to a documentation-only task, with reason.
|
|
99
|
+
|
|
100
|
+
Do not equate test passing with no architectural debt. Identify pre-existing failures separately, but **do not claim a new task passed strict release gates** while required global gates remain failing.
|
|
101
|
+
|
|
102
|
+
## Testing expansion (OBSESSION v1.1)
|
|
103
|
+
|
|
104
|
+
- Behavior tests: `*.test.tsx` beside their React component; use React Testing Library, user-event, Vitest and jsdom.
|
|
105
|
+
- End-to-end journeys: `e2e/*.spec.ts` with Playwright Chromium. Browser downloads are separate (`npx playwright install chromium`).
|
|
106
|
+
- `npm run verify` covers structural checks, scope guard self-tests, Vite+ lint/type checks, Vitest and build, plus npm high-severity audit. It does **not** run browser E2E: CI has a separate browser job.
|
|
107
|
+
- `npm run verify:task` additionally runs the active file-scope manifest check. Missing scope = FAIL.
|
|
108
|
+
- New async pages must test loading, empty, error, unauthorized and not-found behavior. Test failure and retry interactions.
|
|
109
|
+
- Attach browser traces only on failure and never record real credentials.
|