@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/modules/react/architecture-snippets/hooks-query-patterns.md

@@ -1,254 +0,0 @@
-# React — Hooks, React Query & Zustand Patterns
-
-## React Query — Query Hook
-
-```typescript
-// features/order/queries/order.queries.ts
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { orderApi } from '@/api/order.api';
-import type { CreateOrderPayload, Order } from '../types';
-
-// Query key factory — single source of truth for cache invalidation
-export const orderKeys = {
-  all: ['ORDERS'] as const,
-  lists: () => [...orderKeys.all, 'list'] as const,
-  list: (customerId: number) => [...orderKeys.lists(), { customerId }] as const,
-  detail: (id: number) => [...orderKeys.all, 'detail', id] as const,
-};
-
-// @trace.implements=ORD-UC1-SC1
-// @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
-export function useOrderList(customerId: number) {
-  return useQuery({
-    queryKey: orderKeys.list(customerId),
-    queryFn: () => orderApi.getByCustomer(customerId),
-    staleTime: 30_000,
-  });
-}
-
-// @trace.implements=ORD-UC2-SC1
-// @trace.source=specs/order/order-management/bdd/ORD-UC2.feature
-export function useCreateOrder() {
-  const queryClient = useQueryClient();
-
-  return useMutation({
-    mutationFn: (payload: CreateOrderPayload) => orderApi.create(payload),
-    onSuccess: (_, variables) => {
-      // Invalidate order list for this customer
-      queryClient.invalidateQueries({ queryKey: orderKeys.list(variables.customerId) });
-    },
-  });
-}
-```
-
-## API Client (Axios)
-
-```typescript
-// api/order.api.ts
-import { apiClient } from '@/api/client';
-import type { CreateOrderPayload, Order, PaginatedResponse } from '@/features/order/types';
-
-export const orderApi = {
-  getByCustomer: (customerId: number) =>
-    apiClient.get<PaginatedResponse<Order>>('/v1/orders', { params: { customerId } })
-      .then(res => res.data),
-
-  getById: (id: number) =>
-    apiClient.get<Order>(`/v1/orders/${id}`).then(res => res.data),
-
-  create: (payload: CreateOrderPayload) =>
-    apiClient.post<Order>('/v1/orders', payload).then(res => res.data),
-
-  cancel: (id: number) =>
-    apiClient.patch<void>(`/v1/orders/${id}/cancel`).then(res => res.data),
-};
-```
-
-```typescript
-// api/client.ts — Axios instance with auth interceptor
-import axios from 'axios';
-
-export const apiClient = axios.create({
-  baseURL: import.meta.env.VITE_API_URL,
-  headers: { 'Content-Type': 'application/json' },
-});
-
-apiClient.interceptors.request.use(config => {
-  const token = localStorage.getItem('access_token');
-  if (token) config.headers.Authorization = `Bearer ${token}`;
-  return config;
-});
-
-apiClient.interceptors.response.use(
-  res => res,
-  error => {
-    if (error.response?.status === 401) {
-      // redirect to login
-      window.location.href = '/login';
-    }
-    return Promise.reject(error);
-  }
-);
-```
-
-## Zustand Store (Client State)
-
-```typescript
-// features/cart/store/cart.store.ts
-import { create } from 'zustand';
-import { persist } from 'zustand/middleware';
-import type { CartItem } from '../types';
-
-interface CartStore {
-  items: CartItem[];
-  addItem: (item: CartItem) => void;
-  removeItem: (productId: number) => void;
-  clearCart: () => void;
-  total: () => number;
-}
-
-export const useCartStore = create<CartStore>()(
-  persist(
-    (set, get) => ({
-      items: [],
-
-      addItem: (item) =>
-        set(state => {
-          const existing = state.items.find(i => i.productId === item.productId);
-          if (existing) {
-            return {
-              items: state.items.map(i =>
-                i.productId === item.productId
-                  ? { ...i, quantity: i.quantity + item.quantity }
-                  : i
-              ),
-            };
-          }
-          return { items: [...state.items, item] };
-        }),
-
-      removeItem: (productId) =>
-        set(state => ({ items: state.items.filter(i => i.productId !== productId) })),
-
-      clearCart: () => set({ items: [] }),
-
-      total: () => get().items.reduce((sum, i) => sum + i.price * i.quantity, 0),
-    }),
-    { name: 'cart-storage' }
-  )
-);
-```
-
-## Feature Component (Container)
-
-```tsx
-// features/order/components/OrderListPage.tsx
-// @trace.implements=ORD-UC1-SC1
-// @trace.source=specs/order/order-management/bdd/ORD-UC1.feature
-import { useAuth } from '@/hooks/useAuth';
-import { useOrderList } from '../queries/order.queries';
-import { OrderCard } from './OrderCard';
-
-export function OrderListPage() {
-  const { user } = useAuth();
-  const { data: orders, isLoading, isError } = useOrderList(user.id);
-
-  if (isLoading) return <div>Loading...</div>;
-  if (isError)   return <div>Failed to load orders.</div>;
-
-  return (
-    <div className="order-list">
-      {orders?.map(order => (
-        <OrderCard key={order.id} order={order} />
-      ))}
-      {orders?.length === 0 && <p>No orders yet.</p>}
-    </div>
-  );
-}
-```
-
-## React Hook Form + Zod
-
-```tsx
-// features/order/components/CreateOrderForm.tsx
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-import { useCreateOrder } from '../queries/order.queries';
-
-const createOrderSchema = z.object({
-  customerId: z.number().positive(),
-  items: z.array(z.object({
-    productId: z.number().positive(),
-    quantity: z.number().int().min(1),
-  })).min(1, 'At least one item required'),
-});
-
-type CreateOrderForm = z.infer<typeof createOrderSchema>;
-
-export function CreateOrderForm({ customerId }: { customerId: number }) {
-  const { mutate: createOrder, isPending } = useCreateOrder();
-
-  const { register, handleSubmit, formState: { errors } } = useForm<CreateOrderForm>({
-    resolver: zodResolver(createOrderSchema),
-    defaultValues: { customerId, items: [] },
-  });
-
-  const onSubmit = (data: CreateOrderForm) => createOrder(data);
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      {/* form fields */}
-      {errors.items && <p className="error">{errors.items.message}</p>}
-      <button type="submit" disabled={isPending}>
-        {isPending ? 'Creating...' : 'Create Order'}
-      </button>
-    </form>
-  );
-}
-```
-
-## Test with React Testing Library + MSW
-
-```tsx
-// features/order/__tests__/OrderListPage.test.tsx
-// @trace.verifies=ORD-UC1
-// @trace.test_type=integration
-import { render, screen, waitFor } from '@testing-library/react';
-import { http, HttpResponse } from 'msw';
-import { server } from '@/test/server';
-import { renderWithProviders } from '@/test/utils';
-import { OrderListPage } from '../components/OrderListPage';
-
-describe('OrderListPage', () => {
-  it('displays orders after successful fetch', async () => {
-    server.use(
-      http.get('/v1/orders', () =>
-        HttpResponse.json([
-          { id: 1, status: 'pending', customerId: 42, items: [] },
-        ])
-      )
-    );
-
-    renderWithProviders(<OrderListPage />, { user: { id: 42 } });
-
-    expect(screen.getByText('Loading...')).toBeInTheDocument();
-
-    await waitFor(() =>
-      expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
-    );
-
-    expect(screen.getByText('Order #1')).toBeInTheDocument();
-  });
-
-  it('shows empty state when no orders exist', async () => {
-    server.use(http.get('/v1/orders', () => HttpResponse.json([])));
-
-    renderWithProviders(<OrderListPage />, { user: { id: 42 } });
-
-    await waitFor(() =>
-      expect(screen.getByText('No orders yet.')).toBeInTheDocument()
-    );
-  });
-});
-```

package/modules/react/module.yaml

@@ -1,14 +0,0 @@
-name: "React"
-version: "1.0.0"
-description: "React 18 SPA with hooks, React Query, and Zustand"
-language: "TypeScript"
-framework: "React"
-stack_type: "frontend"
-default_layer_order:
-  - Types / interfaces
-  - API client (React Query hooks)
-  - State store (Zustand)
-  - Custom hooks (business logic)
-  - UI components (presentational)
-  - Page / feature components (container)
-test_framework: "Vitest + React Testing Library"

package/modules/react/stack-profile.yaml

@@ -1,63 +0,0 @@
-build:
-  compile: "npm run build"
-  test: "npm test"
-  run: "npm run dev"
-  lint: "npm run lint"
-
-architecture:
-  style: "Feature-based (components → hooks → queries → store)"
-  key_rules:
-    - "Business logic lives in custom hooks, not in components"
-    - "Server state managed by React Query (useQuery / useMutation)"
-    - "Client-only UI state managed by Zustand or useState"
-    - "Components must be pure functions — no direct API calls inside JSX"
-    - "Shared UI primitives in components/ui/, feature logic in features/{name}/"
-    - "Never fetch data directly in a component — use a custom hook"
-  folder_structure: |
-    src/
-    ├── api/              ← axios instance, interceptors
-    ├── components/
-    │   └── ui/           ← reusable primitives (Button, Modal, Table...)
-    ├── features/
-    │   └── {domain}/
-    │       ├── components/   ← feature-specific UI
-    │       ├── hooks/        ← useOrderList, useCreateOrder...
-    │       ├── queries/      ← React Query definitions
-    │       ├── store/        ← Zustand slice (if needed)
-    │       └── types.ts
-    ├── pages/            ← route-level page components
-    └── lib/              ← utilities, formatters, constants
-
-coding_standards:
-  naming:
-    components: "PascalCase (e.g., OrderList, CreateOrderModal)"
-    hooks: "camelCase with 'use' prefix (e.g., useOrderList, useCreateOrder)"
-    query_keys: "SCREAMING_SNAKE_CASE array (e.g., ['ORDER_LIST', customerId])"
-    stores: "camelCase + Store suffix (e.g., useCartStore)"
-    files:
-      component: "{Feature}.tsx"
-      hook: "use{Feature}.ts"
-      query: "{feature}.queries.ts"
-      store: "{feature}.store.ts"
-      types: "{feature}.types.ts"
-  patterns:
-    data_fetching: "React Query (TanStack Query v5)"
-    global_state: "Zustand slices"
-    forms: "React Hook Form + Zod validation"
-    api_client: "Axios with interceptors for auth + error handling"
-    error_boundary: "React ErrorBoundary wraps each feature route"
-
-testing:
-  unit: "Vitest + React Testing Library"
-  e2e: "Playwright or Cypress"
-  patterns:
-    - "Test behavior, not implementation — query by role/label, not className"
-    - "Mock React Query with a QueryClient wrapper in test setup"
-    - "Use MSW (Mock Service Worker) to mock API calls in tests"
-    - "renderWithProviders() helper wraps component with QueryClient + Router"
-
-trace_tags:
-  implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
-  verifies: "// @trace.verifies={UC-ID}"
-  test_type: "// @trace.test_type=unit|integration"

package/modules/react-native/module.yaml

@@ -1,14 +0,0 @@
-name: "React Native"
-version: "1.0.0"
-description: "Cross-platform mobile (iOS + Android) with React Native / Expo"
-language: "TypeScript"
-framework: "React Native"
-stack_type: "mobile"
-default_layer_order:
-  - Types / interfaces
-  - API client (React Query hooks)
-  - State store (Zustand)
-  - Custom hooks (business logic)
-  - UI components (presentational)
-  - Screen / feature components (container)
-test_framework: "Jest + React Native Testing Library"

package/modules/react-native/stack-profile.yaml

@@ -1,56 +0,0 @@
-build:
-  compile: "npx expo export / npx react-native build-android"
-  test: "jest"
-  run: "npx expo start / npx react-native run-ios"
-  lint: "eslint . && tsc --noEmit"
-
-architecture:
-  style: "Feature-based (screens → hooks → queries → store)"
-  key_rules:
-    - "Business logic lives in custom hooks, not in screen components"
-    - "Server state managed by React Query (TanStack Query)"
-    - "Navigation state managed by React Navigation"
-    - "Native modules wrapped in a service layer — never called directly in components"
-    - "Shared UI primitives in src/components/ui/, feature screens in src/features/{name}/"
-  folder_structure: |
-    src/
-    ├── api/              ← axios instance, interceptors
-    ├── components/
-    │   └── ui/           ← reusable primitives (AppButton, AppInput...)
-    ├── features/
-    │   └── {domain}/
-    │       ├── components/
-    │       ├── hooks/
-    │       ├── queries/
-    │       └── screens/
-    ├── navigation/       ← React Navigation stacks/tabs
-    ├── store/            ← Zustand slices
-    └── lib/              ← utils, formatters, constants
-
-coding_standards:
-  naming:
-    components: "PascalCase (e.g., OrderListScreen, CreateOrderForm)"
-    hooks: "camelCase with 'use' prefix (e.g., useOrderList)"
-    screens: "PascalCase + Screen suffix (e.g., OrderDetailScreen)"
-    files:
-      screen: "{Feature}Screen.tsx"
-      component: "{Feature}.tsx"
-      hook: "use{Feature}.ts"
-  patterns:
-    state_management: "Zustand + React Query"
-    navigation: "React Navigation v6 (Stack + Tab + Drawer)"
-    networking: "Axios"
-    forms: "React Hook Form + Zod"
-    storage: "MMKV or AsyncStorage"
-
-testing:
-  unit: "Jest + React Native Testing Library"
-  e2e: "Detox or Maestro"
-  patterns:
-    - "Test by accessibility label or testID — never by style/className"
-    - "Mock native modules in jest setup"
-    - "Use renderWithProviders() with NavigationContainer + QueryClient"
-
-trace_tags:
-  implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"

package/modules/vue/module.yaml

@@ -1,14 +0,0 @@
-name: "Vue"
-version: "1.0.0"
-description: "Vue 3 SPA with Composition API, Pinia, and Vue Query"
-language: "TypeScript"
-framework: "Vue 3"
-stack_type: "frontend"
-default_layer_order:
-  - Types / interfaces
-  - API client (Vue Query / composables)
-  - State store (Pinia)
-  - Composables (business logic)
-  - UI components (presentational)
-  - Page / feature components (container)
-test_framework: "Vitest + Vue Test Utils"

package/modules/vue/stack-profile.yaml

@@ -1,65 +0,0 @@
-build:
-  compile: "npm run build"
-  test: "npm run test"
-  run: "npm run dev"
-  lint: "npm run lint"
-
-architecture:
-  style: "Feature-based (components → composables → queries → store)"
-  key_rules:
-    - "Business logic lives in composables, not in component setup()"
-    - "Server state managed by Vue Query (@tanstack/vue-query)"
-    - "Client-only UI state managed by Pinia stores"
-    - "Components must be pure — no direct API calls inside <template> or setup()"
-    - "Shared UI primitives in components/ui/, feature logic in features/{name}/"
-    - "Never fetch data directly in a component — use a composable"
-    - "Props defined with defineProps<{}>(), emits with defineEmits<{}>()"
-  folder_structure: |
-    src/
-    ├── api/              ← axios instance, interceptors
-    ├── components/
-    │   └── ui/           ← reusable primitives (BaseButton, BaseInput...)
-    ├── features/
-    │   └── {domain}/
-    │       ├── components/   ← feature-specific UI
-    │       ├── composables/  ← useOrderList, useCreateOrder...
-    │       ├── queries/      ← Vue Query definitions
-    │       ├── store/        ← Pinia slice (if needed)
-    │       └── types.ts
-    ├── pages/            ← route-level page components (Vue Router)
-    ├── router/           ← route definitions
-    └── lib/              ← utilities, formatters, constants
-
-coding_standards:
-  naming:
-    components: "PascalCase (e.g., OrderList, CreateOrderModal)"
-    composables: "camelCase with 'use' prefix (e.g., useOrderList, useCreateOrder)"
-    stores: "camelCase + Store suffix (e.g., useCartStore) — defined with defineStore()"
-    query_keys: "SCREAMING_SNAKE_CASE string/array (e.g., ['ORDER_LIST', customerId])"
-    files:
-      component: "{Feature}.vue"
-      composable: "use{Feature}.ts"
-      query: "{feature}.queries.ts"
-      store: "{feature}.store.ts"
-      types: "{feature}.types.ts"
-  patterns:
-    data_fetching: "Vue Query (TanStack Query v5 for Vue)"
-    global_state: "Pinia stores"
-    forms: "VeeValidate + Zod"
-    api_client: "Axios with interceptors for auth + error handling"
-    reactivity: "ref() for primitives, reactive() for objects, computed() for derived state"
-
-testing:
-  unit: "Vitest + Vue Test Utils"
-  e2e: "Playwright or Cypress"
-  patterns:
-    - "Test behavior, not implementation — query by role/label via @testing-library/vue"
-    - "Mock Vue Query with VueQueryPlugin wrapper in test setup"
-    - "Use MSW (Mock Service Worker) to mock API calls in tests"
-    - "mountWithProviders() helper wraps component with Pinia + VueQuery + Router"
-
-trace_tags:
-  implements: "// @trace.implements={UC-ID}-SC{N}"
-  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}-{slug}.feature"
-  verifies: "// @trace.verifies={UC-ID}"
-  test_type: "// @trace.test_type=unit|integration"

package/rules/data-protection.md

@@ -1,80 +0,0 @@
-# Data Protection Rules
-
-> These rules are loaded by `steps/context-loader.md` at the start of every command.
-> AI agents MUST follow these rules without exception.
-
----
-
-## NEVER Read — Sensitive Files
-
-The following file patterns contain credentials, secrets, or private keys.
-**Do NOT read, display, log, or reference their contents under any circumstance.**
-
-### Environment & Secrets
-- `.env`
-- `.env.*` (e.g., `.env.local`, `.env.production`, `.env.staging`)
-- `*.secret`
-- `secrets/` (entire directory)
-- `.secrets/` (entire directory)
-- `*credentials*`
-
-### Cryptographic Keys & Certificates
-- `*.key`
-- `*.pem`
-- `*.p12`
-- `*.pfx`
-- `*.jks`
-- `*.keystore`
-- `*.crt` / `*.cert`
-
-### Framework-Specific Config Files (may contain DB passwords, API keys)
-- `application-prod.yml` / `application-prod.properties`
-- `application-production.yml`
-- `appsettings.Production.json`
-- `appsettings.Staging.json`
-- `database.yml` (Rails)
-- `config/master.key` (Rails)
-- `storage/oauth-private.key`
-
-### Files Matching Dangerous Keywords
-Any file whose name contains (case-insensitive):
-- `password`
-- `passwd`
-- `secret`
-- `private_key`
-- `api_key`
-- `access_token`
-- `auth_token`
-
----
-
-## NEVER Write or Modify
-
-- Any file listed above
-- `*.lock` files that are not package lock files (e.g., `*.lock` outside of `package-lock.json`, `yarn.lock`, `composer.lock`)
-
----
-
-## NEVER Execute via Bash
-
-- Commands that print secrets: `printenv`, `env | grep -i secret`, `cat .env`
-- Commands that expose credentials: `docker inspect`, `kubectl get secret -o yaml`
-- Git commands that may expose history of secrets: `git show`, `git log -p` on config files
-
----
-
-## Safe Alternatives
-
-If context about environment configuration is needed:
-
-1. Ask the user to describe the configuration **without sharing actual values**.
-2. Reference the **structure** of config (keys, not values): "I see you use `DATABASE_URL` — I'll generate code that reads from that variable."
-3. Use placeholder values in generated code: `process.env.DATABASE_URL` or `${DATABASE_URL}`.
-
----
-
-## If a Sensitive File is Accidentally Accessed
-
-1. Do NOT display or repeat any content from the file.
-2. Immediately stop and notify the user: "I've detected a sensitive file. I will not read or use its contents."
-3. Ask the user what they actually need (usually it's the structure, not the values).

package/rules/workflow.md

@@ -1,99 +0,0 @@
-# Workflow Rules
-
-> General AI behavior rules for all spec-driven-docs commands.
-> Loaded by `steps/context-loader.md` at the start of every command.
-
----
-
-## Checkpoints
-
-Ba mức, định nghĩa đầy đủ ở `steps/gate.md` Bước 3a — **đây chỉ là bản tóm tắt, gate là nguồn**:
-
-| Mức | Lệnh nào | `--yes` bỏ qua? |
-|---|---|:---:|
-| **Không chặn** | read-only (`/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs`) | — |
-| **Chặn thường** | mọi lệnh sinh/sửa artifact | ✅ |
-| **Chặn CỨNG** | ghi đè file đã có · `--resume` · migrate · prune | ❌ |
-
-- CHECKPOINT phải nêu **target đã phân giải**, và **mọi cờ 🔴/⚠️ mà context-loader đã tính**
-  (`active_service = unresolved`, `Status ≠ FULL`, CLAUDE.md thiếu, target resolve bằng wildcard).
-- **KHÔNG lặp lại** những gì `[CTX LOADED]` vừa in ngay phía trên. Sạch hết thì CHECKPOINT
-  chỉ hai dòng.
-- `--yes` bỏ qua *chặn thường*, **không** bỏ qua *chặn cứng*, và **không** tắt việc in cờ.
-
-> **Vì sao ba mức thay vì "always show" (G41):** bản cũ viết *"**Always** show a CHECKPOINT"*
-> rồi ngay dòng sau lại cấp một ngoại lệ cho lệnh read-only — mà `gate.md` **không hề thực thi**
-> ngoại lệ đó. Hai file cùng được nạp vào mọi lệnh và nói ngược nhau. Cộng thêm: cổng luôn in
-> ra một bảng giống hệt nhau, 20 lần cho một feature, nên `Y` thành phản xạ và cổng hỏng **âm
-> thầm** — vẫn hiện, vẫn được trả lời, chỉ là không ai đọc. Cổng chỉ ồn khi thật sự có chuyện
-> thì mới được đọc.
-
-## Scope Control
-
-- Work only within the scope explicitly confirmed at CHECKPOINT.
-- Do NOT create files outside the directories specified in `project-context.yaml → paths`.
-- If new scope is discovered mid-command, STOP and ask: "I found additional scope [{description}]. Should I include it? (Y/N)"
-
-## Trace Contract
-
-> **Phạm vi:** mục này áp cho **repo framework**. Ở project consumer, `.agent/` là mirror sinh
-> ra và `bin/` không được cài — contract ở đó là **read-only**: thấy lệch thì **báo**, đừng tự
-> sửa (xem `.agent/README.md`). Việc duy nhất chạy được ở project là **kiểm sổ trace**:
-> `npx @educa-corp/sdd-framework --lint-trace`.
-
-- Contract trace (field `@trace.*`, cột `.tsv`, path pattern, giá trị enum) có **một
-  nguồn-sự-thật máy đọc**: `bin/trace-schema.json`. Bản cho người đọc:
-  `docs/04-reference/trace-schema.md` — giữ hai file đồng bộ.
-- **Canh contract ≠ canh dữ liệu.** `bin/self-check.js` đọc **file lệnh** và kiểm *"lệnh có gọi
-  đúng tên cột không"* — nó không bao giờ mở một `.tsv` thật. `bin/lint-trace.js` mở sổ thật.
-  Cần cả hai: sổ 24 cột được ghi **bằng tay**, hàng chục lần mỗi feature; một dấu tab thiếu ở
-  ô 17 dồn mọi ô sau đó sang trái, ô 21 `status` nhận một ngày tháng, và **không cờ nào bật**.
-  Thêm cột/vocabulary mới → khai binding cho `lint-trace` **ngay**; R8 fail build nếu quên.
-- Đổi contract (thêm/bỏ/đổi nghĩa một field, path, hay giá trị enum) → **sửa
-  `bin/trace-schema.json` TRƯỚC**, rồi mới sửa lệnh. `npm run build` chạy
-  `bin/self-check.js` và **fail** nếu lệnh lệch schema.
-- Field có consumer mà **không có producer** là lỗi chặn build — đó chính là hình dạng
-  của G1 (`@trace.sc_version`: 3 consumer, 0 producer, DRIFT chết mà không ai báo).
-- **Làm mất hiệu lực ≠ ghi đè.** Cột trace có chủ sở hữu rõ ràng — `dev_selftest`/`dev_selftest_at`
-  thuộc `/dev-run-test` · `qc_status`/`qc_run_at` thuộc `/qc-run-test` · `test_count`/`test_classes`
-  thuộc `/dev-gen-test` — và **chỉ chủ được ghi giá trị KHẲNG ĐỊNH** (`pass`/`fail`/số lượng).
-  Nhưng lệnh nào làm giá trị đó **HẾT ĐÚNG** (spec đổi, code đổi) thì **BẮT BUỘC** hạ nó về giá
-  trị "chưa biết" (`not_run` / `—`). Giữ một `pass` đã hết hiệu lực là **báo cáo sai**, không phải
-  tôn trọng quyền sở hữu.
-  *Tiền lệ đúng có sẵn: `/fix-bug` hạ `dev_selftest → not_run` với lý do "code vừa đổi nên tín
-  hiệu self-test cũ hết hiệu lực". Cùng lý do đó áp cho MỌI lệnh làm đổi spec hoặc code.*
-  **Ngoại lệ có chủ ý:** `qc_owner`/`qc_blocked_by` (con trỏ tới bug — spec đổi không làm bug biến
-  mất) và `test_count`/`test_classes` (test vẫn tồn tại trên đĩa; số lượng không sai, chỉ nội dung
-  cũ → **cảnh báo**, không hạ số, để tỷ lệ coverage không nhảy loạn).
-- **Mỗi audit flag phải quan sát được ở CẢ BA tầng.** Mọi giá trị trong
-  `vocabularies.audit_flags` bắt buộc có đủ: **(1)** một counter `{flag_lowercase}_count`
-  trong Step 7 + `summary` của `trace-report.json` · **(2)** một mảng trong `issues` ·
-  **(3)** một khối trong report terminal. Thiếu tầng nào = cờ vô hình ở tầng đó.
-  `bin/self-check.js` R7 ép tầng (1) — **không có ngoại lệ**. Đây là hình dạng của G33:
-  7/10 cờ có counter, 3 cái không, nên dashboard (chỉ đọc `summary`) không tổng hợp
-  được — và bất đối xứng 7/10 là bẫy cho người viết dashboard: đọc `summary` rồi tưởng đủ.
-
-## Code Generation
-
-- Never generate code for files not backed by a `.feature` spec (unless `/fix-bug` or `/debug`).
-- Always add `@trace.implements` tags on controller-level methods.
-- Never overwrite existing business logic without explicit confirmation.
-- Build must pass before committing: run `{conventions.build_command}` and fix errors (max 3 retries).
-
-## File Operations
-
-- Prefer **editing** existing files over replacing them entirely.
-- When creating new files, check if a similar file already exists first.
-- Never delete files unless explicitly instructed.
-
-## Communication
-
-- Report in the language the user writes in (Vietnamese if user uses Vietnamese, English otherwise).
-- Keep reports structured: status, artifacts created, next recommended command.
-- If unsure about business intent, ask — do not guess and generate wrong spec.
-
-## Error Handling
-
-- If a tool call fails (file not found, build error, etc.), report the specific error clearly.
-- Do NOT silently skip errors or pretend success.
-- Suggest a concrete fix, not just "please check the error".