@kirill.konshin/lint 0.7.2 → 0.7.4
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/package.json +7 -3
- package/rules/auth.md +3 -3
- package/rules/db.md +5 -9
- package/rules/github.md +1 -1
- package/rules/gitlab.md +1 -1
- package/rules/i18n.md +3 -0
- package/rules/monorepo-turbo-nx.md +38 -4
- package/rules/mui.md +6 -18
- package/rules/nextjs.md +12 -12
- package/rules/npm-yarn.md +28 -118
- package/rules/nx.md +1 -1
- package/rules/playwright.md +1 -1
- package/rules/react.md +8 -9
- package/rules/tailwind.md +7 -46
- package/rules/testing.md +2 -2
- package/rules/turbo.md +1 -1
- package/rules/typescript.md +5 -1
- package/rules/ui-kit.md +6 -0
- package/skills/lint-db/SKILL.md +21 -0
- package/skills/lint-electron/SKILL.md +7 -6
- package/skills/lint-github/SKILL.md +5 -6
- package/skills/lint-gitlab/SKILL.md +4 -4
- package/skills/lint-migrate/SKILL.md +1 -1
- package/skills/lint-mui/SKILL.md +31 -0
- package/skills/lint-nextjs/SKILL.md +33 -8
- package/skills/lint-npm-yarn/SKILL.md +140 -0
- package/skills/lint-repo/SKILL.md +6 -6
- package/skills/lint-tailwind/SKILL.md +53 -0
- package/skills/lint-webstorm/SKILL.md +2 -2
- package/skills/lint-worktree/SKILL.md +2 -2
- package/skills/spec-author/SKILL.md +2 -2
- package/skills/spec-steward/references/apply.md +1 -1
- package/skills/spec-steward/references/contract.md +1 -1
- package/skills/spec-steward/references/model.md +2 -2
- package/skills/spec-steward/references/review-format.md +4 -4
- package/skills/spec-steward/references/wiring.md +1 -1
- package/skills/spec-steward/references/worker.md +1 -1
- package/skills/spec-tools/references/rules/common.md +1 -1
- package/skills/spec-tools/references/rules/spec-steward.md +1 -1
package/rules/typescript.md
CHANGED
|
@@ -3,16 +3,20 @@ type: always_apply
|
|
|
3
3
|
description: Set of rules for projects with TypeScript, and partially applicable to plain JavaScript
|
|
4
4
|
paths:
|
|
5
5
|
- '**/*.js'
|
|
6
|
+
- '**/*.jsx'
|
|
6
7
|
- '**/*.mjs'
|
|
7
8
|
- '**/*.cjs'
|
|
8
9
|
- '**/*.ts'
|
|
9
10
|
- '**/*.tsx'
|
|
11
|
+
- '**/*.mts'
|
|
12
|
+
- '**/*.cts'
|
|
10
13
|
---
|
|
11
14
|
|
|
12
15
|
- ALL projects must use TypeScript by default
|
|
13
|
-
- JavaScript is acceptable for service scripts, but discouraged
|
|
16
|
+
- JavaScript is acceptable for service scripts, but discouraged; run TypeScript scripts with `node script.ts` (Node type stripping)
|
|
14
17
|
- Do NOT upgrade to TypeScript 7 while tools load the TypeScript JS API (typescript-eslint, ctix, `@arethetypeswrong/core`, Storybook docgen, Next.js type checks, `spec-tools`): TS 7 ships only an unstable API; use its engine through Vite+ type-aware checks
|
|
15
18
|
- With Vite+ (`vite-plus` installed) type-check with `vp check` (`vitePlusConfig` has `typeAware` on by default, the TypeScript 7 engine via tsgolint); NEVER add `tsc --noEmit` scripts; without Vite+ use `tsc --noEmit`
|
|
19
|
+
- In Next.js apps, server-only modules (auth/session, DB access, anything touching secrets, `'use server'` actions files) MUST start with `import 'server-only'` (the npm package, add as dependency) — ENFORCED BY AGENT: no ESLint rule checks this, add it when creating such modules and flag it when reviewing
|
|
16
20
|
- ALL configs should use TypeScript if possible via `defineConfig` or at least import TS type for configuration.
|
|
17
21
|
- Prefer short-circuit evaluation and early exit
|
|
18
22
|
- Use structured logging with context, consider adding function arguments to log:
|
package/rules/ui-kit.md
CHANGED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lint-db
|
|
3
|
+
description: Database procedures for the db rule - LocalStorage / IndexedDB to server migrations, transactional importers, one-off data transfers, steps after a schema change, Neon (HTTP vs pooled driver, Drizzle migrations, Neon Auth with Iron Session). Use when migrating or importing data, changing a schema, or working with Neon.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The binding rules are in [rules/db.md](../../rules/db.md). This skill holds the procedures.
|
|
7
|
+
|
|
8
|
+
# Migrations and Imports
|
|
9
|
+
|
|
10
|
+
- For LocalStorage or IndexedDB migrations, preserve behavior but improve the schema when normalization or consolidation is clearly safer.
|
|
11
|
+
- Make importers transactional, validated, idempotent, and count-verifiable; never delete server data merely because a mutable export became smaller.
|
|
12
|
+
- Keep one-off data transfers out of permanent migration machinery; verify source, destination, schema, counts, and runtime connectivity.
|
|
13
|
+
- After schema changes, generate migrations, confirm no drift, migrate a disposable database in tests, and run typecheck/build/tests.
|
|
14
|
+
|
|
15
|
+
# Neon
|
|
16
|
+
|
|
17
|
+
Only applies if user specifically asked to add Neon as DB, or project already uses Neon as DB.
|
|
18
|
+
|
|
19
|
+
- Prefer Neon HTTP for simple stateless operations; use the pooled serverless driver for transactions, migrations, and connection-oriented work.
|
|
20
|
+
- Use Neon Postgres with Drizzle and checked-in generated migrations.
|
|
21
|
+
- Fold Neon Auth into Iron Session ([rules/auth.md](../../rules/auth.md)): link identity server-side, store app context in the sealed session, then clear the transient Neon session.
|
|
@@ -46,7 +46,7 @@ Scripts: `"start": "vp pack --watch"`, `"build:main": "vp pack"`.
|
|
|
46
46
|
|
|
47
47
|
# Packaging a Next.js Standalone Server
|
|
48
48
|
|
|
49
|
-
In a hoisted workspace (see npm-yarn
|
|
49
|
+
In a hoisted workspace (see [rules/npm-yarn.md](../../rules/npm-yarn.md#hoisting)) Next.js traces the server's dependencies into `.next/standalone/node_modules`, beside the app folder; package both, without Electron:
|
|
50
50
|
|
|
51
51
|
```yaml
|
|
52
52
|
files:
|
|
@@ -60,20 +60,21 @@ files:
|
|
|
60
60
|
|
|
61
61
|
## Gitlab
|
|
62
62
|
|
|
63
|
+
Base the pipeline on the `lint-gitlab` skill (Corepack, install, cache). The Electron build job adds:
|
|
64
|
+
|
|
63
65
|
```yml
|
|
64
66
|
variables:
|
|
65
67
|
USE_HARD_LINKS: 'false' # https://github.com/electron-userland/electron-builder/issues/3179#issuecomment-408347702
|
|
66
68
|
|
|
67
69
|
build:
|
|
68
|
-
image:
|
|
70
|
+
image: <current GitLab macOS image> # a macOS runner builds and signs mac targets
|
|
69
71
|
tags:
|
|
70
|
-
-
|
|
72
|
+
- saas-macos-medium-m1
|
|
71
73
|
script:
|
|
72
|
-
- yarn --immutable
|
|
73
74
|
- yarn build
|
|
74
75
|
- rm -rf electron/dist/mac # some cleanup to make artifacts leaner
|
|
75
|
-
|
|
76
|
-
-
|
|
76
|
+
rules:
|
|
77
|
+
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
|
|
77
78
|
artifacts:
|
|
78
79
|
paths:
|
|
79
80
|
- electron/dist
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lint-github
|
|
3
|
-
description:
|
|
3
|
+
description: Reference GitHub Actions setup - composite setup and Nx-cache actions, install / lint / test / build / release jobs, Yarn and Nx Cloud caching, OIDC npm publishing. Use when writing, reviewing or debugging a `.github` workflow or action.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Reference CI: two local composite actions and a workflow. Install and cache rules: npm-yarn.md
|
|
6
|
+
Reference CI: two local composite actions and a workflow. Install and cache rules: [rules/npm-yarn.md](../../rules/npm-yarn.md#install-on-ci) and [rules/github.md](../../rules/github.md).
|
|
7
7
|
|
|
8
8
|
- The `install` job fills the Yarn cache (`setup` with `yarn-cache: warm`).
|
|
9
9
|
- The checks run after it as parallel jobs. They only restore the cache (`yarn-cache: restore`).
|
|
10
10
|
- The publish job needs all checks.
|
|
11
11
|
- A workflow with one job, or with jobs that run one after another, has no `install` job. It uses the default `yarn-cache: save`.
|
|
12
|
-
- Self-hosted runners with a shared cache volume: remove the `Use local Yarn cache` step and the Yarn cache steps from `setup` (npm-yarn
|
|
12
|
+
- Self-hosted runners with a shared cache volume: remove the `Use local Yarn cache` step and the Yarn cache steps from `setup` (the `lint-npm-yarn` skill, "Install on CI").
|
|
13
13
|
|
|
14
14
|
# With Nx Cloud (`nxCloudId` in `nx.json`)
|
|
15
15
|
|
|
@@ -329,9 +329,8 @@ jobs:
|
|
|
329
329
|
|
|
330
330
|
needs: [lint, test, build]
|
|
331
331
|
|
|
332
|
-
# If project publishes to NPM
|
|
333
|
-
|
|
334
|
-
if: github.repository == 'kirill-konshin/utils'
|
|
332
|
+
# If project publishes to NPM; forks skip the release
|
|
333
|
+
if: github.repository == '<owner>/<repo>'
|
|
335
334
|
permissions:
|
|
336
335
|
id-token: write # Required for OIDC trusted publishing
|
|
337
336
|
contents: write
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lint-gitlab
|
|
3
|
-
description:
|
|
3
|
+
description: Reference GitLab CI pipeline - install / lint / test / build jobs, Yarn and Nx caches, Nx Cloud tokens, a shared cache volume. Use when writing, reviewing or debugging `.gitlab-ci.yml`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# With Nx Cloud (`nxCloudId` in `nx.json`)
|
|
@@ -126,8 +126,8 @@ build:
|
|
|
126
126
|
stage: build
|
|
127
127
|
script:
|
|
128
128
|
- yarn build
|
|
129
|
-
|
|
130
|
-
-
|
|
129
|
+
rules:
|
|
130
|
+
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
|
|
131
131
|
artifacts:
|
|
132
132
|
paths:
|
|
133
133
|
- web/build
|
|
@@ -135,7 +135,7 @@ build:
|
|
|
135
135
|
|
|
136
136
|
# Shared Cache Volume
|
|
137
137
|
|
|
138
|
-
Use this when all runners mount the same volume (npm-yarn
|
|
138
|
+
Use this when all runners mount the same volume (the `lint-npm-yarn` skill, "Install on CI"). The packages stay on the volume. No job uploads or downloads them.
|
|
139
139
|
|
|
140
140
|
Runner config (Kubernetes executor, a ReadWriteMany PVC):
|
|
141
141
|
|
|
@@ -13,7 +13,7 @@ Only what changes between versions; the target setup is the package README (`nod
|
|
|
13
13
|
|
|
14
14
|
# 0.6 -> 0.7
|
|
15
15
|
|
|
16
|
-
0.7 recommends Vite+. Keep the ESLint / Prettier / lint-staged exports only if the user declines Vite+. Do not use Yarn PnP (npm-yarn.md). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
|
|
16
|
+
0.7 recommends Vite+. Keep the ESLint / Prettier / lint-staged exports only if the user declines Vite+. Do not use Yarn PnP ([rules/npm-yarn.md](../../rules/npm-yarn.md)). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
|
|
17
17
|
|
|
18
18
|
- **Prerequisites**: Node `^22.18 || ^24.11 || >=26`, Vite 8+, Vitest 4.1+, `node-modules` linker
|
|
19
19
|
- **Set up** Vite+ by hand per the README "Vite+" section — not `vp migrate`: it copies every expanded ESLint rule, writes absolute paths and broken regexes, and rewrites dependencies; if it was run, replace its `lint` / `fmt` blocks with `vitePlusConfig`
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lint-mui
|
|
3
|
+
description: MUI and Toolpad conventions - barrel imports of `@mui/material` / `@mui/icons-material` (direct imports in libraries), stable `*Classes` class names in `sx`, safe-area insets in the theme, admin pages and login with `@toolpad/core` and `@kirill.konshin/mui/admin`, `optimizePackageImports` with Next.js. Use when writing or reviewing code that uses MUI or Toolpad, or building an admin interface.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Imports
|
|
7
|
+
|
|
8
|
+
- Always import components or icons this way: `import { Paper, Button } from '@mui/material';` and `import { Xxx } from '@mui/icons-material';`
|
|
9
|
+
- See [Next.js](#nextjs)
|
|
10
|
+
- Exception: if developing a library use direct imports with minimal bundle footprint (libraries may not be used with barrel handling)
|
|
11
|
+
|
|
12
|
+
# Class Names
|
|
13
|
+
|
|
14
|
+
- To use MUI default classes always use stable minifiable class names:
|
|
15
|
+
- Import: `import { inputClasses } from '@mui/material';` or `import { inputClasses } from '@mui/material/Input';` (see [Imports](#imports))
|
|
16
|
+
- Usage: `<Box sx={{ [``& .${inputClasses.root}``]: { /* styles */ } }}><Input /></Box>`
|
|
17
|
+
|
|
18
|
+
# Theme
|
|
19
|
+
|
|
20
|
+
- Define safe-area insets globally or in the theme; consume through `sx`, never repeated `env(...)`
|
|
21
|
+
|
|
22
|
+
# Admin Pages & Login
|
|
23
|
+
|
|
24
|
+
- ALWAYS use MUI for admin interfaces (Tailwind is ONLY for user-facing sites, see [rules/tailwind.md](../../rules/tailwind.md))
|
|
25
|
+
- ALWAYS use [`@toolpad/core`](https://mui.com/toolpad/core/introduction/) for admin page layouts and login screens: `AppProvider`, `DashboardLayout`, `PageContainer`, `SignInPage`
|
|
26
|
+
- ALWAYS prefer `@kirill.konshin/mui/admin` (`AdminAppProvider`, `AdminDashboardLayout`, `AdminSignInPage`) over hand-rolled `NextAppProvider`/`DashboardLayout`/`SignInPage` boilerplate; `AdminSignInPage.loginAction` takes `loginFormAction` from `@kirill.konshin/auth` (see [rules/auth.md](../../rules/auth.md))
|
|
27
|
+
- Prefer Toolpad built-ins (navigation, dialogs, notifications, CRUD) over hand-rolled equivalents
|
|
28
|
+
|
|
29
|
+
# Next.js
|
|
30
|
+
|
|
31
|
+
- With Next.js, `experimental.optimizePackageImports` MUST list the barrel-heavy MUI packages: `defineNextConfig` sets them, see the `lint-nextjs` skill
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lint-nextjs
|
|
3
|
-
description:
|
|
3
|
+
description: Next.js App Router patterns - typed `LayoutProps` / `PageProps`, auth-guarded layouts, async `params` / `searchParams`, page and component file placement, what `defineNextConfig` sets in `next.config.ts` (incl. MUI `optimizePackageImports`). Use when writing or reviewing Next.js pages, layouts, route handlers or `next.config.ts`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Layouts
|
|
@@ -27,15 +27,23 @@ Prefer `/app/(auth)/layout.tsx` as root layout for auth protection. This won't c
|
|
|
27
27
|
|
|
28
28
|
Route Handlers are not protected by layouts, so add auth check there too.
|
|
29
29
|
|
|
30
|
+
Use `@kirill.konshin/auth` (see [rules/auth.md](../../rules/auth.md)); the guard runs inside `<Suspense>`:
|
|
31
|
+
|
|
30
32
|
```tsx
|
|
31
|
-
import
|
|
32
|
-
|
|
33
|
-
import {
|
|
33
|
+
import { type ReactNode, Suspense } from 'react';
|
|
34
|
+
|
|
35
|
+
import { auth } from '@/auth';
|
|
36
|
+
|
|
37
|
+
export default function Layout({ children }: LayoutProps<'/dashboard'>) {
|
|
38
|
+
return (
|
|
39
|
+
<Suspense>
|
|
40
|
+
<Protected>{children}</Protected>
|
|
41
|
+
</Suspense>
|
|
42
|
+
);
|
|
43
|
+
}
|
|
34
44
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
redirect('/login');
|
|
38
|
-
}
|
|
45
|
+
async function Protected({ children }: { children: ReactNode }) {
|
|
46
|
+
await auth.redirectNonAuthenticated(); // redirects to urls.login
|
|
39
47
|
return <>{children}</>;
|
|
40
48
|
}
|
|
41
49
|
```
|
|
@@ -57,3 +65,20 @@ export default async function Page({ params, searchParams }: PageProps<'/blog/[s
|
|
|
57
65
|
return <h1>Blog post: {slug}</h1>;
|
|
58
66
|
}
|
|
59
67
|
```
|
|
68
|
+
|
|
69
|
+
# Files
|
|
70
|
+
|
|
71
|
+
- Do not make dummy pages that only import components, pages can be client, and should have most logic baked in, including one-off components (not exported)
|
|
72
|
+
- Reusable components should be in `src/components`
|
|
73
|
+
- As exception, separate component files are allowed to be in `src/app` next to relevant pages if one-off component is large so page itself becomes bloated, but `src/components` should not be polluted with one-offs, ask user if not sure
|
|
74
|
+
- Example: `actions.ts` for `'use server'` actions while page is `'use client'`
|
|
75
|
+
- Admin pages: use as less custom JSX as possible — prefer Toolpad built-ins (`DashboardLayout`, `PageContainer`, `SignInPage`) over hand-rolled components
|
|
76
|
+
|
|
77
|
+
# `next.config.ts`
|
|
78
|
+
|
|
79
|
+
- Create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath, NEVER the barrel — Next transpiles `next.config.ts` to CJS and `require`s it outside any bundler): sets `cacheComponents`, `typedRoutes`, `experimental.typedEnv`, `reactStrictMode: false` and an exhaustive `experimental.optimizePackageImports` (`@mui/*`, `@toolpad/core`, `@fortawesome/*`, `@gravity-ui/*`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons` — extra entries are ignored, missing ones cost dev startup and bundle size, see MUI below)
|
|
80
|
+
|
|
81
|
+
## MUI
|
|
82
|
+
|
|
83
|
+
- When MUI is used with Next.js ALWAYS add barrel-heavy packages to `experimental.optimizePackageImports`: `@mui/material`, `@mui/system`, `@mui/icons-material`, `@mui/lab`, `@mui/x-data-grid`, `@toolpad/core`, plus the other usual suspects (`@fortawesome/*`, `@gravity-ui/icons`, `@gravity-ui/uikit`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons`)
|
|
84
|
+
- Prefer `defineNextConfig` from `@kirill.konshin/next/config` which sets the exhaustive list — extra entries are ignored, missing ones cost dev startup and bundle size (see `next.config.ts` above)
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lint-npm-yarn
|
|
3
|
+
description: Yarn / npm / pnpm details for the npm-yarn rule - hoisting edge cases (Electron, pnpm, binary packagers), version pinning templates (`overrides`, `resolutions`, Yarn constraints), `.yarnrc.yml` template, CI install on a shared cache volume and speed-ups, Yalc linking procedure, first npm publish with OIDC. Use when changing package manager configuration, CI install, local package linking or publishing a new package.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The binding rules are in [rules/npm-yarn.md](../../rules/npm-yarn.md). This skill holds the details.
|
|
7
|
+
|
|
8
|
+
# Hoisting
|
|
9
|
+
|
|
10
|
+
- Hoist everything: the historical React Native/Expo/Electron reasons for hoisting limits are obsolete (Metro follows symlinks since RN 0.72, Expo SDK 54+ supports monorepos with any strategy, hoisting limits break Electron Forge and duplicate React instances)
|
|
11
|
+
- Electron + pnpm needs MORE hoisting, not less: set `node-linker=hoisted` (or `shamefully-hoist=true`) in `.npmrc`, otherwise packaged apps miss dependencies (electron-builder/electron-vite guidance)
|
|
12
|
+
- Electron + Next.js `output: 'standalone'` in a hoisted workspace: Next.js traces dependencies into `.next/standalone/node_modules`, beside the app folder `.next/standalone/<app>` — package that folder too (electron-builder `files`), never limit hoisting for it; see the `lint-electron` skill
|
|
13
|
+
- Binary packagers don't need hoisting limits either: bundle to a single file first, then package — node_modules layout becomes irrelevant; build Node SEA executables with `vp pack` (`exe`, Node ≥ 25.7) when Vite+ is used, else `@yao-pkg/pkg` (maintained fork of the deprecated `vercel/pkg`); a Next.js standalone server cannot be bundled into one file: ship its files as SEA assets and extract them on the first start
|
|
14
|
+
- Shared root configs (e.g. `@kirill.konshin/lint`) must be able to resolve leaf tools (`next`, `tailwindcss`, `storybook`, `jest`) from the workspace root:
|
|
15
|
+
- npm / Yarn: default hoisting already exposes them
|
|
16
|
+
- pnpm: add to `.npmrc`: `public-hoist-pattern[]=next`, `public-hoist-pattern[]=tailwindcss`, `public-hoist-pattern[]=storybook`, `public-hoist-pattern[]=jest` (`*eslint*`/`*prettier*` are hoisted by default)
|
|
17
|
+
- Yarn PnP: declare the tools at the workspace root as well
|
|
18
|
+
- If lint fails with "not resolvable from the workspace root": apply the above or add the package to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
|
|
19
|
+
|
|
20
|
+
# Consistent versions
|
|
21
|
+
|
|
22
|
+
In monorepos pin versions of sub-packages to the root; these packages cause issues when versions drift.
|
|
23
|
+
|
|
24
|
+
https://github.com/raineorshine/npm-check-updates/issues/1332#issuecomment-1717862332 https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides
|
|
25
|
+
|
|
26
|
+
Root `package.json`:
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"overrides": {
|
|
31
|
+
"@types/node": "$@types/node",
|
|
32
|
+
"@types/react": "$@types/react",
|
|
33
|
+
"@types/react-dom": "$@types/react-dom",
|
|
34
|
+
"next": "$next",
|
|
35
|
+
"eslint": "$eslint",
|
|
36
|
+
"typescript": "$typescript",
|
|
37
|
+
"vite": "$vite"
|
|
38
|
+
},
|
|
39
|
+
"resolutions": {
|
|
40
|
+
"@types/node": "^26",
|
|
41
|
+
"@types/react": "^19",
|
|
42
|
+
"@types/react-dom": "^19",
|
|
43
|
+
"eslint": "^10",
|
|
44
|
+
"next": "^16",
|
|
45
|
+
"typescript": "^6",
|
|
46
|
+
"vite": "^8"
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
All other `package.json`:
|
|
52
|
+
|
|
53
|
+
```jsonc
|
|
54
|
+
{
|
|
55
|
+
"devDependencies": {
|
|
56
|
+
"next": "^16.0.0", // except next, see nextjs.md
|
|
57
|
+
"typescript": "^6.0.0",
|
|
58
|
+
},
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Yarn does not apply npm `overrides`; `defineYarnConfig` reads them as constraints together with `resolutions`, keeps non-peer leaf ranges equal, and falls back to the listed default packages when `overrides` is absent.
|
|
63
|
+
|
|
64
|
+
Every package with `"packageManager": "yarn@..."` MUST directly install `@yarnpkg/types` and use:
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
/** @type {import('@yarnpkg/types')} */
|
|
68
|
+
const { defineConfig } = require('@yarnpkg/types');
|
|
69
|
+
const { defineYarnConfig } = require('@kirill.konshin/lint/yarn');
|
|
70
|
+
|
|
71
|
+
module.exports = defineConfig(defineYarnConfig());
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Run `yarn constraints --fix` after dependency changes.
|
|
75
|
+
|
|
76
|
+
# `.yarnrc.yml`
|
|
77
|
+
|
|
78
|
+
Make sure `yarnPath` is not specified, rely on `packageManager` in `package.json` and Corepack.
|
|
79
|
+
|
|
80
|
+
```yml
|
|
81
|
+
approvedGitRepositories:
|
|
82
|
+
- '**'
|
|
83
|
+
|
|
84
|
+
# print install-time script output (postinstall / prepare, dependency builds) live instead of buffering it into a log
|
|
85
|
+
enableInlineBuilds: true
|
|
86
|
+
|
|
87
|
+
enableScripts: true
|
|
88
|
+
|
|
89
|
+
nodeLinker: node-modules
|
|
90
|
+
|
|
91
|
+
npmMinimalAgeGate: 0
|
|
92
|
+
|
|
93
|
+
# own packages are exempt from the minimum-release-age quarantine (npmMinimalAgeGate)
|
|
94
|
+
npmPreapprovedPackages:
|
|
95
|
+
- '@kirill.konshin/*'
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
# Install on CI
|
|
99
|
+
|
|
100
|
+
The basic rules are in [rules/npm-yarn.md](../../rules/npm-yarn.md#install-on-ci). Platform steps: the `lint-github` skill and the `lint-gitlab` skill.
|
|
101
|
+
|
|
102
|
+
- Exception: a shared cache volume. IF all runners mount the same volume (for example a Kubernetes PVC):
|
|
103
|
+
- Set `YARN_ENABLE_GLOBAL_CACHE=true` and put the Yarn global folder on the volume (`YARN_GLOBAL_FOLDER`). Do not use the CI cache for packages.
|
|
104
|
+
- Hardlinks do not cross filesystems. Yarn hardlinks package files from `<globalFolder>/index`. The `node-modules` linker then copies instead and downgrades `nmMode: hardlinks-global` to `hardlinks-local`. The `pnpm` linker has no fallback: it fails with "cross-device link".
|
|
105
|
+
- With Yarn's `nodeLinker: pnpm`, put `pnpmStoreFolder` on the same volume as the global folder, one folder per branch (`/cache/yarn/store/$CI_COMMIT_REF_SLUG`). The link step then takes seconds.
|
|
106
|
+
- Each Yarn `pnpm` install deletes all store entries that it does not use. The per-branch folder keeps installs on other branches away from your store.
|
|
107
|
+
- With pnpm, set `store-dir` on the volume.
|
|
108
|
+
- Clean the volume with a scheduled job: the global cache only grows, and the stores of deleted branches stay.
|
|
109
|
+
- IF `yarn install` is still the CI bottleneck, measure it and evaluate alternatives. The principles of [Speed up NPM/Yarn install in Gitlab](https://www.konshin.org/publications/speed-up-npm-yarn-install-in-gitlab) ([Medium](https://medium.com/disdj/speed-up-npm-yarn-install-in-gitlab-1434437f9857)) still apply. Its tools are outdated.
|
|
110
|
+
- A faster linker: Yarn's `nodeLinker: pnpm` often links faster than `node-modules`, and pnpm is faster still. Both layouts are strict and not hoisted (see Hoisting). Undeclared dependencies fail, and Electron needs a hoisted layout. `@kirill.konshin/lint` is not verified with them.
|
|
111
|
+
- Jobs that need only some workspaces: `yarn workspaces focus <workspace>`
|
|
112
|
+
- A CI image with the dependencies installed
|
|
113
|
+
- IF in doubt, keep `nodeLinker: node-modules`.
|
|
114
|
+
|
|
115
|
+
# Yalc (Local Package Linking)
|
|
116
|
+
|
|
117
|
+
Test unpublished `@kirill.konshin/*` packages in sibling projects (yalc is a root devDependency of the `kirill-konshin/utils` repository):
|
|
118
|
+
|
|
119
|
+
1. `yarn nx run @kirill.konshin/<pkg>:build`
|
|
120
|
+
2. `cd packages/<pkg> && yarn yalc publish` (after changes: `yarn yalc publish --push` updates all linked consumers)
|
|
121
|
+
3. In the consumer: `npx yalc link @kirill.konshin/<pkg>` (or the yalc binary from the `kirill-konshin/utils` repository)
|
|
122
|
+
|
|
123
|
+
Rules:
|
|
124
|
+
|
|
125
|
+
- ALWAYS use `yalc link` (symlink mode: `node_modules/<pkg>` → local `.yalc/<pkg>` copy), NEVER `yalc add` — `add` writes `file:.yalc/...` into package.json
|
|
126
|
+
- While linked, `package.json`, `yarn.lock` and `.yarnrc.yml` MUST NOT be modified by the link — link artifacts break CI/other machines and must NEVER be committed; gitignore `.yalc/` and `yalc.lock` in the consumer
|
|
127
|
+
- The real dependency (e.g. `"@kirill.konshin/auth": "^0.0.1"`) is committed separately; the consumer's `yarn.lock` can only be updated after the version is actually published to npm
|
|
128
|
+
- The consumer resolves the linked package's own dependencies from its node_modules — they must be installed there (usually already are as the consumer's own deps)
|
|
129
|
+
- A later `yarn install` in the consumer removes the symlink — re-run `yalc link`
|
|
130
|
+
- Unlinking: `yalc remove --all` cleans `.yalc/` and `yalc.lock` but leaves dangling symlinks in `node_modules` — delete them before `yarn install`
|
|
131
|
+
- Yarn 4.17+ quarantines packages published <24h ago (`npmMinimalAgeGate`) — consumers need `npmPreapprovedPackages: ["@kirill.konshin/*"]` in `.yarnrc.yml` to install own packages right after release (older Yarn errors on that key — upgrade the consumer via `packageManager` first)
|
|
132
|
+
- `.yarnrc.local.yml` is NOT a thing (open Yarn feature request, local overrides only via `YARN_*` env vars) and yalc runs NO registry (it is a file store in `~/.yalc`), so a registry override cannot replace linking — `yalc link` is the only mode that leaves all manifests untouched
|
|
133
|
+
|
|
134
|
+
# First Publish with OIDC
|
|
135
|
+
|
|
136
|
+
- Never bootstrap, publish, or push a release without explicit approval.
|
|
137
|
+
- Bootstrap a new npm package once from a locally authenticated session with `npm publish --access public --tag bootstrap`; complete npm's interactive 2FA challenge, or use `--otp=<code>` for TOTP.
|
|
138
|
+
- Configure its GitHub trusted publisher with the repository owner, repository name and release workflow file. For `@kirill.konshin/*` packages these are: organization/user `kirill-konshin`, repository `utils`, workflow `release.yml`, optional environment `npm-publish`. Check **Allow npm publish**.
|
|
139
|
+
- Under Publishing access, check **Require two-factor authentication and disallow bypass 2FA tokens (recommended)**; OIDC publishes remain allowed and should be used for every normal release.
|
|
140
|
+
- The first conventional `feat` release establishes the normal `latest` version.
|
|
@@ -18,18 +18,18 @@ Follow `node_modules/@kirill.konshin/lint/README.md`, reconciling (never blindly
|
|
|
18
18
|
|
|
19
19
|
Vite+ is the default. Use the ESLint + Prettier flow only when the user declines Vite+.
|
|
20
20
|
|
|
21
|
-
Do not use Yarn PnP (npm-yarn.md). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
|
|
21
|
+
Do not use Yarn PnP ([rules/npm-yarn.md](../../rules/npm-yarn.md)). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
|
|
22
22
|
|
|
23
23
|
### Vite+
|
|
24
24
|
|
|
25
|
-
Write the config by hand. `vp migrate` is only an optional first pass: it copies every expanded ESLint rule, absolute paths and broken regexes into `vite.config.ts`, so clean up after it as `lint-migrate` describes.
|
|
25
|
+
Write the config by hand. `vp migrate` is only an optional first pass: it copies every expanded ESLint rule, absolute paths and broken regexes into `vite.config.ts`, so clean up after it as the `lint-migrate` skill describes.
|
|
26
26
|
|
|
27
27
|
1. **Install** — add `vite-plus`, `@kirill.konshin/lint` (+ `eslint` only for Nx module-boundary rules); pin `vite`/`vitest` at the root (README "Yarn constraints").
|
|
28
28
|
2. **Config** — root `vite.config.ts`: `defineConfig(vitePlusConfig({ ...project blocks }, { ...toggles }))`; move project rule overrides into `lint.rules` / `lint.overrides`, ignores into `ignorePatterns`. Keep `.editorconfig`.
|
|
29
|
-
3. **Hooks** — `lint-prepare init && vp config` in `prepare`/`postinstall` — in this order: `vp config` fills the Vite+ section `lint-prepare` writes into `AGENTS.md` (same choice as below), `.vite-hooks/pre-commit` with `vp staged`; scripts `lint: vp check --fix`, `lint:staged: vp staged`; workspace-wide scripts move from `yarn workspaces foreach` to `vp run -r` (npm-yarn
|
|
29
|
+
3. **Hooks** — `lint-prepare init && vp config` in `prepare`/`postinstall` — in this order: `vp config` fills the Vite+ section `lint-prepare` writes into `AGENTS.md` (same choice as below), `.vite-hooks/pre-commit` with `vp staged`; scripts `lint: vp check --fix`, `lint:staged: vp staged`; workspace-wide scripts move from `yarn workspaces foreach` to `vp run -r` ([rules/npm-yarn.md](../../rules/npm-yarn.md)).
|
|
30
30
|
4. **Tests/builds** — tests import from `vite-plus/test`; libraries `vp pack`, apps `vp build`.
|
|
31
|
-
5. **CI** — `vp check` (no `--fix`), see `lint-github`
|
|
32
|
-
6. **IDEA** — apply `lint-webstorm` if the repo has a JetBrains `.idea`.
|
|
31
|
+
5. **CI** — `vp check` (no `--fix`), see the `lint-github` skill or the `lint-gitlab` skill.
|
|
32
|
+
6. **IDEA** — apply the `lint-webstorm` skill if the repo has a JetBrains `.idea`.
|
|
33
33
|
7. **Install** — run the package manager; then `vp check` and the tests.
|
|
34
34
|
|
|
35
35
|
### ESLint + Prettier
|
|
@@ -38,7 +38,7 @@ Write the config by hand. `vp migrate` is only an optional first pass: it copies
|
|
|
38
38
|
2. **Config** — create/reconcile `.editorconfig`, `eslint.config.mjs` and `.prettierrc.mjs` (pass `defineLintConfig` options as needed — e.g. `defaultIgnore: { importMetaUrl: import.meta.url }`, `next: { rootDir }` — and keep project rule overrides).
|
|
39
39
|
3. **Lint-staged** — create/reconcile `.lintstagedrc.mjs`.
|
|
40
40
|
4. **Husky** — `prepare/postinstall` (`prepare` by default, `postinstall` if Yarn 2+ is used AND root package.json is **private**) script; `.husky/pre-commit`, plus `eslint`/`prettier`/`lint`/`lint:staged` scripts. Drop a legacy `lint:all` if it duplicates `lint`.
|
|
41
|
-
5. **IDEA** — apply `lint-webstorm` if the repo has a JetBrains `.idea`.
|
|
41
|
+
5. **IDEA** — apply the `lint-webstorm` skill if the repo has a JetBrains `.idea`.
|
|
42
42
|
6. **Install** — run the package manager (`yarn` / `npm install` / `pnpm install`) so the new deps and Husky hooks land. Under Yarn 2+ check if root `package.json` has `prepare` script, and if it does, run it.
|
|
43
43
|
|
|
44
44
|
Check the README's "Issues" section before debugging a lint crash.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lint-tailwind
|
|
3
|
+
description: Tailwind details for the tailwind rule - the safe-area `@utility` template and the eslint-plugin-tailwindcss / Oxlint setup (entry CSS detection, `cssConfigPath`, scoping, resolution errors). Use when adding safe-area utilities, or when Tailwind lint is set up, crashes or skips.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The binding rules are in [rules/tailwind.md](../../rules/tailwind.md). This skill holds the details.
|
|
7
|
+
|
|
8
|
+
# Safe-Area Utilities
|
|
9
|
+
|
|
10
|
+
```css
|
|
11
|
+
@utility top-safe {
|
|
12
|
+
top: 1.5rem;
|
|
13
|
+
top: max(1.5rem, env(safe-area-inset-top, 0px));
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
@utility right-safe {
|
|
17
|
+
right: 1.5rem;
|
|
18
|
+
right: max(1.5rem, env(safe-area-inset-right, 0px));
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
@utility bottom-safe {
|
|
22
|
+
bottom: 1.5rem;
|
|
23
|
+
bottom: max(1.5rem, env(safe-area-inset-bottom, 0px));
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
@utility left-safe {
|
|
27
|
+
left: 1.5rem;
|
|
28
|
+
left: max(1.5rem, env(safe-area-inset-left, 0px));
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
# ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
|
|
33
|
+
|
|
34
|
+
- With Vite+ the same plugin runs as an Oxlint JS plugin with the same detection; pass `tailwind: { cssConfigPath }` as `vitePlusConfig` options instead of `eslint.config.mjs`
|
|
35
|
+
- The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
|
|
36
|
+
- Zero-config happy path: when the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned across the root + every workspace package, `.gitignore`-aware), rules auto-enable with that entry
|
|
37
|
+
- Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
|
|
38
|
+
- `tailwindcss` must be resolvable from the workspace root — if lint fails with "not resolvable from the workspace root", hoist it (see the `lint-npm-yarn` skill, "Hoisting") or add it to root `devDependencies`; run eslint with `LINT_DEBUG=1` to trace detection
|
|
39
|
+
- Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
|
|
40
|
+
- pass `cssConfigPath` to pick one (if others are not useful) OR
|
|
41
|
+
- create multiple leaf `eslint.config.ts` per app (if ALL need to be linted)
|
|
42
|
+
- When detection can't see `tailwindcss` (e.g. it lives only in leaf packages of a monorepo), force it with `tailwind: true` — then a missing entry CSS is a HARD ERROR instead of a silent skip
|
|
43
|
+
- ONLY when auto-find finds nothing (or several entries) pass the MANDATORY entry explicitly in `eslint.config.mjs`:
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
import { defineLintConfig } from '@kirill.konshin/lint';
|
|
47
|
+
|
|
48
|
+
export default defineLintConfig({
|
|
49
|
+
tailwind: {
|
|
50
|
+
cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the package root
|
|
51
|
+
},
|
|
52
|
+
});
|
|
53
|
+
```
|
|
@@ -5,7 +5,7 @@ description: Templates and checks for JetBrains IDEA / WebStorm `.idea` project
|
|
|
5
5
|
|
|
6
6
|
# Check
|
|
7
7
|
|
|
8
|
-
Compare the project's `.idea` files with the templates below and
|
|
8
|
+
Compare the project's `.idea` files with the templates below and [rules/webstorm.md](../../rules/webstorm.md), list every discrepancy, ask before fixing:
|
|
9
9
|
|
|
10
10
|
- Template settings missing or different in the project's files
|
|
11
11
|
- Excluded folders out of sync between `.gitignore`, `.idea/%projectName%.iml` (usually only one IML file) and `.idea/indexLayout.xml` - look only in these files, infer nothing else
|
|
@@ -149,7 +149,7 @@ When the project uses `vite-plus`: the [Oxc plugin](https://plugins.jetbrains.co
|
|
|
149
149
|
|
|
150
150
|
# GitIgnore
|
|
151
151
|
|
|
152
|
-
Excluded folders follow the baseline of
|
|
152
|
+
Excluded folders follow the baseline of [rules/webstorm.md](../../rules/webstorm.md).
|
|
153
153
|
|
|
154
154
|
## Configure `.idea/.gitignore`:
|
|
155
155
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: lint-worktree
|
|
3
|
-
description:
|
|
3
|
+
description: Git worktrees in `.worktrees` and the JetBrains IDEA / WebStorm module-name clash they cause. Use when creating, attaching or removing a git worktree.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
- Prefer creating worktrees inside the main repo in `.worktrees` directory
|
|
@@ -25,4 +25,4 @@ description: Describes how to work with GIT Worktrees
|
|
|
25
25
|
1. Rename the `.iml` back and run `git update-index --no-skip-worktree` on every file marked above.
|
|
26
26
|
2. Restore them with `git checkout -- <files>`.
|
|
27
27
|
3. Redo the rename afterwards.
|
|
28
|
-
- A worktree created **inside** the main checkout (e.g. `.worktrees/<name>`, where agents put theirs) is indexed by the main project as part of itself, a second copy of every source and `node_modules`, and the main project's save actions start reformatting the worktree's files. Exclude its folder in the main checkout's `.idea/%projectName%.iml` (`<excludeFolder url="file://$MODULE_DIR$/.worktrees" />`) and list it in `.gitignore`, so the excluded-folders baseline of
|
|
28
|
+
- A worktree created **inside** the main checkout (e.g. `.worktrees/<name>`, where agents put theirs) is indexed by the main project as part of itself, a second copy of every source and `node_modules`, and the main project's save actions start reformatting the worktree's files. Exclude its folder in the main checkout's `.idea/%projectName%.iml` (`<excludeFolder url="file://$MODULE_DIR$/.worktrees" />`) and list it in `.gitignore`, so the excluded-folders baseline of [rules/webstorm.md](../../rules/webstorm.md) holds. Attaching such a worktree can replace the main checkout's own entry in its `.idea/modules.xml`: keep both — the main `.idea/%projectName%.iml` and the worktree's renamed one — then reload the project. A nested worktree shows as its own module node inside the tree, not as a separate top-level project; for a top-level entry, create the worktree outside the main checkout.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-author
|
|
3
|
-
description: Write or edit a capability specification in openspec/specs — the default direct-edit path
|
|
4
|
-
allowed-tools: Bash(openspec:*), Bash(spec-tools:*), Bash(
|
|
3
|
+
description: Write or edit a capability specification in openspec/specs — the default direct-edit path. Use when adding or changing a requirement or scenario, unless the user asks for the /opsx delta flow.
|
|
4
|
+
allowed-tools: Bash(openspec:*), Bash(spec-tools:*), Bash(yarn openspec:*), Bash(yarn spec-tools:*), Bash(npx openspec:*), Bash(npx spec-tools:*), Bash(node:*), Bash(git diff*), Bash(git log*), Read, Edit, Write, Glob, Grep
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Write or edit a capability specification in place. This is the **default** path for specification work; the `/opsx:*` commands drive the full delta flow and run only when the user asks for them.
|
|
@@ -6,7 +6,7 @@ The owner has answered a review file ([review-format.md](review-format.md)). Pro
|
|
|
6
6
|
2. **Accepted (`✅`, `✅ <comment>`).** Apply the proposal, changed as the comment tells.
|
|
7
7
|
- Before you change a requirement, read the requirements that name it and that it names, and the code and tests involved. A fix must not break a sibling.
|
|
8
8
|
- A rule that several repositories share changes identically in each. `steward align` shows the drift.
|
|
9
|
-
- When a change moves guidance to a new place, put it where
|
|
9
|
+
- When a change moves guidance to a new place, put it where [rules/agent.md](../../../rules/agent.md) tells, remove each copy, and reference it from its old place.
|
|
10
10
|
- Add `applied: "R<round> — <what changed, with paths>"` to the item. A second application makes `applied` a list.
|
|
11
11
|
3. **Rejected (`❌`, `❌ <comment>`).** Keep the rule as it is, or follow the owner's other instruction. Record what you did in `applied`.
|
|
12
12
|
4. **Comment only.** Examine the item again, and change the proposal or the explanation in place. Move the owner's comment into `previousDecision: "R<n>: <comment>"` and set `decision` to `""`. A comment is never acceptance.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# The spec-steward contract
|
|
2
2
|
|
|
3
|
-
What `spec-steward` checks and reports in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. A repository's constitution states only its own choices — the `--binds` globs it passes, the jobs that run the gate, the audits it runs and where it publishes — and points here for the rest. How a specification is written is [model.md](model.md); this file is what the tool does with it. `steward.test.
|
|
3
|
+
What `spec-steward` checks and reports in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. A repository's constitution states only its own choices — the `--binds` globs it passes, the jobs that run the gate, the audits it runs and where it publishes — and points here for the rest. How a specification is written is [model.md](model.md); this file is what the tool does with it. `spec-tools/src/steward/steward.test.ts` proves the cases below.
|
|
4
4
|
|
|
5
5
|
Terms used throughout:
|
|
6
6
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# The specification model
|
|
2
2
|
|
|
3
|
-
Where a piece of guidance lives is decided by
|
|
3
|
+
Where a piece of guidance lives is decided by [rules/agent.md](../../../rules/agent.md), shipped by `@kirill.konshin/lint`; in a repository it is `.agents/rules/agent.md`. Read it there; this file covers only what is specific to the specifications themselves. What the gate checks mechanically — citations, binding, markers, size lines, the scenario ratchet — is [contract.md](contract.md).
|
|
4
4
|
|
|
5
5
|
## A rule in `openspec/specs` is a contract
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ Normative force is carried by the RFC 2119 keywords — MUST, MUST NOT, REQUIRED
|
|
|
10
10
|
|
|
11
11
|
A specification describes only real, existing behaviour. What is knowingly absent or incomplete is recorded as a [Known gap](#advisory-known-gap-or-neither), never written as though implemented and never left as unmarked silence.
|
|
12
12
|
|
|
13
|
-
Apply the two litmus questions from
|
|
13
|
+
Apply the two litmus questions from [rules/agent.md](../../../rules/agent.md); then the decision test:
|
|
14
14
|
|
|
15
15
|
> **Name the observable failure this rule prevents, and the cheapest evidence that would catch it.**
|
|
16
16
|
|
|
@@ -16,8 +16,8 @@ R-001:
|
|
|
16
16
|
confidence: 85
|
|
17
17
|
rule:
|
|
18
18
|
text: |-
|
|
19
|
-
The server SHALL promote
|
|
20
|
-
location: '
|
|
19
|
+
The server SHALL promote Xxx…
|
|
20
|
+
location: 'APP openspec/specs/system-overview/logging/spec.md:47'
|
|
21
21
|
wrong: |
|
|
22
22
|
The rule names the exact log fields. A field change breaks the rule with no effect in production.
|
|
23
23
|
proposal: |
|
|
@@ -37,10 +37,10 @@ R-002:
|
|
|
37
37
|
rules:
|
|
38
38
|
- text: |-
|
|
39
39
|
WHEN the dev server starts THEN it seeds the demo account
|
|
40
|
-
location: '
|
|
40
|
+
location: 'APP openspec/specs/apps/runtime/spec.md:88'
|
|
41
41
|
- text: |-
|
|
42
42
|
The local database SHALL reset on each start
|
|
43
|
-
location: '
|
|
43
|
+
location: 'APP openspec/specs/apps/db/spec.md:12'
|
|
44
44
|
note: 'the reset is also in the README'
|
|
45
45
|
wrong: |
|
|
46
46
|
Both rules apply only on a developer machine. A violation has no effect in production.
|
|
@@ -12,7 +12,7 @@ A skill is discovered at the agent's discretion, so it cannot be the only thing
|
|
|
12
12
|
|
|
13
13
|
These five points keep to the placement rules:
|
|
14
14
|
|
|
15
|
-
- Nothing restates
|
|
15
|
+
- Nothing restates [rules/agent.md](../../../rules/agent.md) or the repository's own rules.
|
|
16
16
|
- The OPSX `context` stays untouched: it already carries `AGENTS.md`.
|
|
17
17
|
- The hook is a no-op where the skill is not installed, so teammates without it are not blocked.
|
|
18
18
|
|