@kirill.konshin/lint 0.5.2 → 0.5.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.
Files changed (40) hide show
  1. package/README.md +1 -1
  2. package/dist/lintPrepare.d.ts +9 -8
  3. package/dist/lintPrepare.d.ts.map +1 -1
  4. package/dist/lintPrepare.js +20 -14
  5. package/package.json +5 -3
  6. package/rules/github.md +0 -76
  7. package/rules/gitlab.md +0 -72
  8. package/rules/nextjs.md +2 -55
  9. package/rules/openspec.md +12 -0
  10. package/rules/storybook.md +2 -0
  11. package/rules/tailwind.md +1 -1
  12. package/rules/testing.md +1 -0
  13. package/rules/webstorm.md +6 -214
  14. package/skills/lint-github/SKILL.md +78 -0
  15. package/skills/lint-gitlab/SKILL.md +76 -0
  16. package/skills/lint-nextjs/SKILL.md +59 -0
  17. package/skills/{lint-repo.md → lint-repo/SKILL.md} +1 -1
  18. package/skills/lint-webstorm/SKILL.md +201 -0
  19. package/skills/lint-worktree/SKILL.md +28 -0
  20. package/skills/spec-steward/SKILL.md +76 -0
  21. package/skills/spec-steward/references/apply.md +18 -0
  22. package/skills/spec-steward/references/audit.md +57 -0
  23. package/skills/spec-steward/references/contract.md +186 -0
  24. package/skills/spec-steward/references/criteria.md +59 -0
  25. package/skills/spec-steward/references/model.md +71 -0
  26. package/skills/spec-steward/references/review-format.md +61 -0
  27. package/skills/spec-steward/references/wiring.md +19 -0
  28. package/skills/spec-steward/scripts/lib/align.mjs +126 -0
  29. package/skills/spec-steward/scripts/lib/checks.mjs +584 -0
  30. package/skills/spec-steward/scripts/lib/citations.mjs +156 -0
  31. package/skills/spec-steward/scripts/lib/corpus.mjs +259 -0
  32. package/skills/spec-steward/scripts/lib/coverage.mjs +124 -0
  33. package/skills/spec-steward/scripts/lib/evidence.mjs +335 -0
  34. package/skills/spec-steward/scripts/lib/git.mjs +138 -0
  35. package/skills/spec-steward/scripts/lib/review.mjs +347 -0
  36. package/skills/spec-steward/scripts/lib/scan.mjs +364 -0
  37. package/skills/spec-steward/scripts/lib/util.mjs +161 -0
  38. package/skills/spec-steward/scripts/lib/wire.mjs +331 -0
  39. package/skills/spec-steward/scripts/steward.mjs +350 -0
  40. package/skills/spec-steward/workflows/audit.js +539 -0
@@ -0,0 +1,78 @@
1
+ ---
2
+ name: lint-github
3
+ description: Describes how to work with Github & example workflow as a reference which essential jobs and concepts usual Github Workflow should have
4
+ ---
5
+
6
+ ```yml
7
+ name: Release
8
+
9
+ on:
10
+ push:
11
+ branches:
12
+ - main
13
+
14
+ # If project publishes to NPM
15
+ permissions:
16
+ id-token: write # Required for OIDC
17
+ contents: read
18
+
19
+ concurrency: ${{ github.workflow }}-${{ github.ref }}
20
+
21
+ jobs:
22
+ release:
23
+ name: Release
24
+ runs-on: ubuntu-latest
25
+ env:
26
+ TURBO_CACHE_DIR: .turbo # if project uses Turbo
27
+ YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
28
+
29
+ # If project publishes to NPM
30
+ # https://davistobias.com/articles/adding-changeset/#2.1.b-adding-changeset-to-github-workflows
31
+ if: github.repository == 'kirill-konshin/utils'
32
+ permissions:
33
+ id-token: write # Required for OIDC trusted publishing
34
+ contents: write
35
+ pull-requests: write
36
+
37
+ steps:
38
+ - name: Checkout Repo
39
+ uses: actions/checkout@v4
40
+
41
+ - name: Enable Corepack
42
+ run: corepack enable
43
+
44
+ - name: Setup Node.js
45
+ uses: actions/setup-node@v6
46
+ with:
47
+ node-version: 24
48
+ registry-url: 'https://registry.npmjs.org'
49
+ cache: yarn
50
+ cache-dependency-path: yarn.lock
51
+
52
+ #TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
53
+ #TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
54
+ - name: Cache Turbo
55
+ uses: actions/cache@v6
56
+ with:
57
+ path: .turbo
58
+ key: ${{ runner.os }}-turbo-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
59
+ restore-keys: |
60
+ ${{ runner.os }}-turbo-${{ github.run_id }}-${{ github.run_attempt }}-
61
+ ${{ runner.os }}-turbo-
62
+
63
+ - name: Cache Nx
64
+ uses: actions/cache@v6
65
+ with:
66
+ path: .nx/cache
67
+ key: ${{ runner.os }}-nx-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
68
+ restore-keys: |
69
+ ${{ runner.os }}-nx-${{ github.run_id }}-${{ github.run_attempt }}-
70
+ ${{ runner.os }}-nx-
71
+
72
+ - name: Install dependencies
73
+ run: yarn install --immutable
74
+
75
+ # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this block skipped
76
+ - name: Prepare
77
+ run: yarn prepare
78
+ ```
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: lint-gitlab
3
+ description: Describes how to work with Gitlab Pipelines & example pipeline as a reference which essential jobs and concepts usual Gitlab project should have
4
+ ---
5
+
6
+ ```yml
7
+ image: node:lts
8
+
9
+ variables:
10
+ YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
11
+
12
+ cache:
13
+ - key:
14
+ prefix: yarn
15
+ files:
16
+ - yarn.lock # dependencies cached based on lockfile
17
+ paths:
18
+ - .yarn/cache
19
+ policy: pull-push
20
+ # Job-specific keys prevent parallel jobs from replacing each other's local build cache.
21
+ - key: build-$CI_JOB_NAME_SLUG-$CI_COMMIT_REF_SLUG
22
+ fallback_keys:
23
+ - build-$CI_JOB_NAME_SLUG-$CI_DEFAULT_BRANCH
24
+ paths:
25
+ - .turbo
26
+ - .nx/cache
27
+ - '**/.tscache'
28
+ - '**/.tsbuildinfo'
29
+ - '**/.next/cache'
30
+ policy: pull-push
31
+
32
+ stages:
33
+ - install
34
+ - test
35
+ - build
36
+
37
+ # separate so that cache can pre-populate if other steps would fail, it speeds things up
38
+ before_script:
39
+ - corepack enable
40
+ - yarn install --immutable
41
+ - yarn prepare # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this line skipped
42
+
43
+ install:
44
+ stage: install
45
+ script:
46
+ - echo Done
47
+
48
+ lint:
49
+ stage: test
50
+ script:
51
+ - yarn lint
52
+
53
+ test:
54
+ stage: test
55
+ image: mcr.microsoft.com/playwright:v1.50.0-noble # keep in sync with installed Playwright version
56
+ artifacts:
57
+ when: always
58
+ paths:
59
+ - test-results
60
+ - test-results-html
61
+ reports:
62
+ junit: test-results/junit.xml
63
+ script:
64
+ - yarn test:playwright # https://playwright.dev/docs/ci#running-headed xvfb-run yarn test:playwright
65
+
66
+ # Not needed for Vercel-hosted projects
67
+ build:
68
+ stage: build
69
+ script:
70
+ - yarn build
71
+ only:
72
+ - master
73
+ artifacts:
74
+ paths:
75
+ - web/build
76
+ ```
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: lint-nextjs
3
+ description: Describes key patterns how to work with Next.js
4
+ ---
5
+
6
+ # Layouts
7
+
8
+ Always use https://nextjs.org/docs/app/api-reference/file-conventions/layout#layout-props-helper:
9
+
10
+ ```tsx
11
+ import React from 'react';
12
+
13
+ export default function Layout({ children, analytics }: LayoutProps<'/dashboard'>) {
14
+ return (
15
+ <>
16
+ {children}
17
+ {/* If you have app/dashboard/@analytics, it appears as a typed slot: */}
18
+ {analytics}
19
+ </>
20
+ );
21
+ }
22
+ ```
23
+
24
+ ## Check auth in layouts pattern
25
+
26
+ Prefer `/app/(auth)/layout.tsx` as root layout for auth protection. This won't create path segment, but will protect all routes under it.
27
+
28
+ Route Handlers are not protected by layouts, so add auth check there too.
29
+
30
+ ```tsx
31
+ import React from 'react';
32
+ import { redirect } from 'next/navigation';
33
+ import { getToken } from '@/lib/auth';
34
+
35
+ export default async function Layout({ children }: LayoutProps<'/dashboard'>) {
36
+ if (!(await getToken())) {
37
+ redirect('/login');
38
+ }
39
+ return <>{children}</>;
40
+ }
41
+ ```
42
+
43
+ # Pages
44
+
45
+ - https://nextjs.org/docs/app/api-reference/file-conventions/dynamic-routes
46
+ - https://nextjs.org/docs/app/getting-started/layouts-and-pages#rendering-with-search-params
47
+ - https://nextjs.org/docs/app/getting-started/layouts-and-pages#creating-a-dynamic-segment
48
+
49
+ Always use https://nextjs.org/docs/app/api-reference/file-conventions/page#page-props-helper.
50
+
51
+ Always use the following pattern for all pages:
52
+
53
+ ```tsx
54
+ export default async function Page({ params, searchParams }: PageProps<'/blog/[slug]'>) {
55
+ const { slug } = await params;
56
+ const { filter } = await searchParams;
57
+ return <h1>Blog post: {slug}</h1>;
58
+ }
59
+ ```
@@ -20,7 +20,7 @@ Follow @README.md, reconciling (never blindly overwriting project-specific overr
20
20
  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).
21
21
  3. **Lint-staged** — create/reconcile `.lintstagedrc.mjs`.
22
22
  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`.
23
- 5. **IDEA** — apply the file-scope glob patterns if the repo has a JetBrains `.idea`.
23
+ 5. **IDEA** — apply `lint-webstorm` if the repo has a JetBrains `.idea`.
24
24
  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.
25
25
 
26
26
  Check the README's "Issues" section before debugging a lint crash.
@@ -0,0 +1,201 @@
1
+ ---
2
+ name: lint-webstorm
3
+ description: Templates and checks for JetBrains IDEA / WebStorm `.idea` project files - excluded folders, Prettier & ESLint scopes, VCS, code style, Tailwind, JSON schemas, index exclusions. Use when setting up, checking or fixing a project's `.idea` configuration.
4
+ ---
5
+
6
+ # Check
7
+
8
+ Compare the project's `.idea` files with the templates below and the `webstorm` rule, list every discrepancy, ask before fixing:
9
+
10
+ - Template settings missing or different in the project's files
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
12
+ - Git worktrees - see the `lint-worktree` skill
13
+
14
+ # Configure `.idea/%projectName%.iml`
15
+
16
+ ```xml
17
+ <?xml version="1.0" encoding="UTF-8"?>
18
+ <module type="WEB_MODULE" version="4">
19
+ <component name="NewModuleRootManager">
20
+ <content url="file://$MODULE_DIR$">
21
+ <excludeFolder url="file://$MODULE_DIR$/.yarn" />
22
+ <excludePattern pattern=".turbo" />
23
+ <excludePattern pattern=".nx" />
24
+ <excludePattern pattern="build" />
25
+ <excludePattern pattern="coverage" />
26
+ <excludePattern pattern="dist" />
27
+ </content>
28
+ <orderEntry type="inheritedJdk" />
29
+ <orderEntry type="sourceFolder" forTests="false" />
30
+ </component>
31
+ </module>
32
+ ```
33
+
34
+ # Configure `.idea/jsLibraryMappings.xml`
35
+
36
+ ```xml
37
+ <?xml version="1.0" encoding="UTF-8"?>
38
+ <project version="4">
39
+ <component name="JavaScriptLibraryMappings">
40
+ <includedPredefinedLibrary name="Node.js Core" />
41
+ </component>
42
+ </project>
43
+ ```
44
+
45
+ # Configure `.idea/prettier.xml`
46
+
47
+ ```xml
48
+ <?xml version="1.0" encoding="UTF-8"?>
49
+ <project version="4">
50
+ <component name="PrettierConfiguration">
51
+ <option name="myConfigurationMode" value="AUTOMATIC" />
52
+ <option name="myRunOnSave" value="true" />
53
+ <option name="myRunOnReformat" value="true" />
54
+ <option name="myFilesPattern" value="{**/*,*}.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue,css,scss,sass,less,yml,yaml,json,json5,graphql,graphqls,xml}" />
55
+ </component>
56
+ </project>
57
+ ```
58
+
59
+ # Configure `.idea/jsLinters/eslint.xml`
60
+
61
+ ```xml
62
+ <?xml version="1.0" encoding="UTF-8"?>
63
+ <project version="4">
64
+ <component name="EslintConfiguration">
65
+ <files-pattern value="**/*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}" />
66
+ <option name="fix-on-save" value="true" />
67
+ </component>
68
+ </project>
69
+ ```
70
+
71
+ # Configure `.idea/vcs.xml`
72
+
73
+ ```xml
74
+ <?xml version="1.0" encoding="UTF-8"?>
75
+ <project version="4">
76
+ <component name="CommitMessageInspectionProfile">
77
+ <profile version="1.0">
78
+ <inspection_tool class="BodyLimit" enabled="true" level="WARNING" enabled_by_default="true">
79
+ <option name="RIGHT_MARGIN" value="100" />
80
+ </inspection_tool>
81
+ <inspection_tool class="SubjectBodySeparation" enabled="true" level="WARNING" enabled_by_default="true" />
82
+ <inspection_tool class="SubjectLimit" enabled="true" level="WARNING" enabled_by_default="true">
83
+ <option name="RIGHT_MARGIN" value="100" />
84
+ </inspection_tool>
85
+ </profile>
86
+ </component>
87
+ <component name="GitSharedSettings">
88
+ <option name="FORCE_PUSH_PROHIBITED_PATTERNS">
89
+ <list />
90
+ </option>
91
+ </component>
92
+ <component name="VcsDirectoryMappings">
93
+ <mapping directory="$PROJECT_DIR$" vcs="Git" />
94
+ </component>
95
+ </project>
96
+ ```
97
+
98
+ # GitIgnore
99
+
100
+ Excluded folders follow the baseline of the `webstorm` rule.
101
+
102
+ ## Configure `.idea/.gitignore`:
103
+
104
+ ```gitignore
105
+ # Default ignored files
106
+ /shelf/
107
+ /workspace.xml
108
+ # Editor-based HTTP Client requests
109
+ /httpRequests/
110
+ AugmentWebviewStateStore.xml
111
+ ```
112
+
113
+ # Configure `.idea/codeStyles/codeStyleConfig.xml`
114
+
115
+ ```xml
116
+ <component name="ProjectCodeStyleConfiguration">
117
+ <state>
118
+ <option name="PREFERRED_PROJECT_CODE_STYLE" value="DiS" />
119
+ </state>
120
+ </component>
121
+ ```
122
+
123
+ # Configure `.idea/tailwindcss.xml`
124
+
125
+ Applies if project is using Tailwind.
126
+
127
+ ```xml
128
+ <?xml version="1.0" encoding="UTF-8"?>
129
+ <project version="4">
130
+ <component name="TailwindSettings">
131
+ <option name="lspConfiguration" value="{&#10; &quot;inspectPort&quot;: null,&#10; &quot;emmetCompletions&quot;: false,&#10; &quot;classAttributes&quot;: [&quot;class&quot;, &quot;className&quot;, &quot;activeClassName&quot;, &quot;disabledClassName&quot;, &quot;ngClass&quot;, &quot;class:list&quot;],&#10; &quot;classFunctions&quot;: [],&#10; &quot;codeActions&quot;: true,&#10; &quot;codeLens&quot;: true,&#10; &quot;hovers&quot;: true,&#10; &quot;suggestions&quot;: true,&#10; &quot;validate&quot;: true,&#10; &quot;colorDecorators&quot;: true,&#10; &quot;rootFontSize&quot;: 16,&#10; &quot;lint&quot;: {&#10; &quot;cssConflict&quot;: &quot;warning&quot;,&#10; &quot;invalidApply&quot;: &quot;error&quot;,&#10; &quot;invalidScreen&quot;: &quot;error&quot;,&#10; &quot;invalidVariant&quot;: &quot;error&quot;,&#10; &quot;invalidConfigPath&quot;: &quot;error&quot;,&#10; &quot;invalidTailwindDirective&quot;: &quot;error&quot;,&#10; &quot;invalidSourceDirective&quot;: &quot;error&quot;,&#10; &quot;recommendedVariantOrder&quot;: &quot;warning&quot;,&#10; &quot;usedBlocklistedClass&quot;: &quot;warning&quot;&#10; },&#10; &quot;showPixelEquivalents&quot;: true,&#10; &quot;includeLanguages&quot;: {&#10; &quot;ftl&quot;: &quot;html&quot;,&#10; &quot;jinja&quot;: &quot;html&quot;,&#10; &quot;jinja2&quot;: &quot;html&quot;,&#10; &quot;smarty&quot;: &quot;html&quot;,&#10; &quot;tmpl&quot;: &quot;gohtml&quot;,&#10; &quot;cshtml&quot;: &quot;html&quot;,&#10; &quot;vbhtml&quot;: &quot;html&quot;,&#10; &quot;razor&quot;: &quot;html&quot;&#10; },&#10; &quot;files&quot;: {&#10; &quot;exclude&quot;: [&#10; &quot;**/.git/**&quot;,&#10; &quot;**/.hg/**&quot;,&#10; &quot;**/.svn/**&quot;,&#10; &quot;**/node_modules/**&quot;,&#10; &quot;**/.yarn/**&quot;,&#10; &quot;**/.venv/**&quot;,&#10; &quot;**/venv/**&quot;,&#10; &quot;**/.next/**&quot;,&#10; &quot;**/.parcel-cache/**&quot;,&#10; &quot;**/.svelte-kit/**&quot;,&#10; &quot;**/.turbo/**&quot;,&#10; &quot;**/__pycache__/**&quot;&#10; ]&#10; },&#10; &quot;experimental&quot;: {&#10; &quot;configFile&quot;: null,&#10; &quot;classRegex&quot;: [&#10; &quot;Classes\\s*=\\s*['\&quot;`]([^'\&quot;`]*?)['\&quot;`]&quot;, &quot;['\&quot;`]([^'\&quot;`]*?)['\&quot;`]&quot;,&#10; &quot;Styles\\s*=\\s*['\&quot;`]([^'\&quot;`]*?)['\&quot;`]&quot;, &quot;['\&quot;`]([^'\&quot;`]*?)['\&quot;`]&quot;&#10; ]&#10; }&#10;}" />
132
+ </component>
133
+ </project>
134
+ ```
135
+
136
+ # Configure `.idea/jsonSchemas.xml`
137
+
138
+ ```xml
139
+ <?xml version="1.0" encoding="UTF-8"?>
140
+ <project version="4">
141
+ <component name="JsonSchemaMappingsProjectConfiguration">
142
+ <state>
143
+ <map>
144
+ <entry key="Gemini CLI settings">
145
+ <value>
146
+ <SchemaInfo>
147
+ <option name="name" value="Gemini CLI settings" />
148
+ <option name="relativePathToSchema" value="https://raw.githubusercontent.com/google-gemini/gemini-cli/refs/heads/main/schemas/settings.schema.json" />
149
+ <option name="applicationDefined" value="true" />
150
+ <option name="patterns">
151
+ <list>
152
+ <Item>
153
+ <option name="path" value=".gemini/settings.json" />
154
+ </Item>
155
+ </list>
156
+ </option>
157
+ </SchemaInfo>
158
+ </value>
159
+ </entry>
160
+ <entry key="Yarn Config (.yarnrc.yml)">
161
+ <value>
162
+ <SchemaInfo>
163
+ <option name="name" value="Yarn Config (.yarnrc.yml)" />
164
+ <option name="relativePathToSchema" value="https://yarnpkg.com/configuration/yarnrc.json" />
165
+ <option name="applicationDefined" value="true" />
166
+ <option name="patterns">
167
+ <list>
168
+ <Item>
169
+ <option name="path" value=".yarnrc.yml" />
170
+ </Item>
171
+ </list>
172
+ </option>
173
+ </SchemaInfo>
174
+ </value>
175
+ </entry>
176
+ </map>
177
+ </state>
178
+ </component>
179
+ </project>
180
+ ```
181
+
182
+ # Configure `indexLayout.xml`
183
+
184
+ Ban build directories from search using examples:
185
+
186
+ ```xml
187
+ <?xml version="1.0" encoding="UTF-8"?>
188
+ <project version="4">
189
+ <component name="UserContentModel">
190
+ <attachedFolders />
191
+ <explicitIncludes>
192
+ </explicitIncludes>
193
+ <explicitExcludes>
194
+ <Path>.worktrees</Path>
195
+ <Path>path-to-eve/.eve</Path>
196
+ <Path>path-to-vite/dist</Path>
197
+ <Path>path-to-next/.next</Path>
198
+ </explicitExcludes>
199
+ </component>
200
+ </project>
201
+ ```
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: lint-worktree
3
+ description: Describes how to work with GIT Worktrees
4
+ ---
5
+
6
+ - Prefer creating worktrees inside the main repo in `.worktrees` directory
7
+ - Directory `.worktrees` has to be gitignored, banned from IDEA indexing, and marked as excluded
8
+
9
+ # Git Worktrees & JetBrains IDEA / WebStorm
10
+
11
+ `.idea/%projectName%.iml`, `.idea/modules.xml` and `.idea/.name` are usually tracked. Every git worktree therefore checks out a module with the same name as the main checkout's, and WebStorm refuses to attach it: `Cannot attach project: Module name '%projectName%' already exists`.
12
+
13
+ - When creating a worktree, ALWAYS give it a distinct module and project name derived from the branch, e.g. `App Name: Workspace Name` for `workspace-name`:
14
+ 1. **Rename** — do not copy — `.idea/%projectName%.iml` to `.idea/%projectName% %Branch Title%.iml`. The module name is the file name, and attaching the worktree registers whichever `.iml` it finds: a copy beside the original still attaches as `%projectName%`.
15
+ 2. Point `.idea/modules.xml` at the renamed file.
16
+ 3. Write the same name into `.idea/.name`.
17
+ 4. A main project the worktree is attached to lists it in its own `.idea/modules.xml`: point that entry at the renamed file too.
18
+ - Keep the rename local, and NEVER commit it or merge it back:
19
+ - The tracked `.iml` first: stage the branch's own edits to it (`git add .idea/%projectName%.iml`), then `git update-index --skip-worktree .idea/%projectName%.iml`, then rename. The staged content is what the branch commits; the rename never shows as a deletion. An edit the branch later makes to the renamed file has to be staged back the same way.
20
+ - Ignore the renamed file in the shared `.git/info/exclude` with the pattern `.idea/%projectName% *.iml`.
21
+ - A **tracked** `.idea/modules.xml` or `.idea/.name`: run `git update-index --skip-worktree` on it.
22
+ - An **untracked** one (often `modules.xml` is in `.idea/.gitignore` and `.name` does not exist yet): `skip-worktree` fails on it, so leave it to `.idea/.gitignore` or add it to the shared `.git/info/exclude` as well (e.g. `.idea/.name`).
23
+ - Verify with `git status --short .idea`: nothing from the rename is listed, only the staged edits.
24
+ - Before a rebase, merge or checkout that updates those files (tracked ones only):
25
+ 1. Rename the `.iml` back and run `git update-index --no-skip-worktree` on every file marked above.
26
+ 2. Restore them with `git checkout -- <files>`.
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 the `webstorm` rule 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.
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: spec-steward
3
+ description: Guard, audit and repair an OpenSpec specification corpus. Use when auditing specs for corpus quality (the whole corpus, a change, or one capability), producing or processing a spec review file (review rounds where the owner answers items with ⬜ / ✅ / ❌), aligning rules shared by several repositories, wiring the spec guard (edit hook, AGENTS.md routing, OPSX config) into a repository, or when the repository's spec gate, `spec-steward check` or the edit hook reports a finding. Deterministic scripts do the mechanical work; the skill supplies the procedure. It does not audit code conformance; the repository's own conformance audit does — the `verify-spec` skill where the repository has one.
4
+ ---
5
+
6
+ # Spec steward
7
+
8
+ Procedures for an OpenSpec corpus. Four things live elsewhere and are not repeated here:
9
+
10
+ - the hard constraints for editing specs — the scoped rule `.agents/rules/openspec.md`
11
+ - where any guidance belongs — `.agents/rules/agent.md`
12
+ - the specification model (REQUIRED versus ⚠️ ADVISORY, Known gaps, the evidence ladder, what is not evidence, how requirements and scenarios are written) — [references/model.md](references/model.md)
13
+ - what the gate checks and emits (citations, binding, markers, size lines, the scenario ratchet, base resolution, exit codes, the coverage report, the evidence JSON) — [references/contract.md](references/contract.md)
14
+
15
+ `steward` below means the `spec-steward` bin that `@kirill.konshin/lint` installs (`node_modules/.bin/spec-steward`); where the bin is absent, `node <this skill's folder>/scripts/steward.mjs`. Inside a Yarn script the bin resolves only once the installed release carries it (a yalc link adds `node_modules/.bin/spec-steward`, which Yarn's script PATH does not include); until then call it by path. It has no dependencies and needs Node ≥ 20 and git. Every command takes `--root NAME=path` (repeatable, for several repositories) and `--specs <dir>` (default `openspec/specs`).
16
+
17
+ ## Pick the procedure
18
+
19
+ | The situation | Do |
20
+ | --------------------------------------------------------------- | ---------------------------- |
21
+ | You edited a spec, a proposal, or a test or code that cites one | [Check](#check) |
22
+ | The spec gate, the edit hook or `steward check` reported one | [Check](#check) |
23
+ | Audit the corpus, a change, or a capability | [Audit](references/audit.md) |
24
+ | The owner has answered a review file | [Apply](references/apply.md) |
25
+ | A rule lives in several repositories | [Align](#align) |
26
+ | Set up or repair the guard in a repository | [Wire](references/wiring.md) |
27
+
28
+ ## Check
29
+
30
+ Where the repository's `AGENTS.md` names a spec gate in its Checks list, such as `yarn spec:gates`, run that gate: it runs `steward check --base auto` with the repository's `--binds`. Elsewhere run `steward check --base auto` yourself. It compares the working tree with the branch point and checks the corpus and the files citing it. Add `--file <path>` to scope it, `--json` for machines, `--strict` to fail on warnings, and `--fix` for the safe mechanical repairs. A kind marked _base only_ runs only when a base is set, and under a base the prompts cover only what the diff added or edited.
31
+
32
+ | Kind | Severity | What to do |
33
+ | --- | --- | --- |
34
+ | `dangling-citation` | error | Fix the path or anchor, or remove the citation. A citation is an optional pointer; the one rule is that it resolves. |
35
+ | `renamed-anchor` | error, base only | `--fix` rewrites every citation of an anchor the diff renamed. |
36
+ | `duplicate-anchor` | error | Two headings in one spec render the same slug. Rename one. |
37
+ | `duplicate-requirement` | error | One requirement name in two capabilities, or one body twice. Keep it in the capability that owns the behaviour and reference it from the other. |
38
+ | `size` | error past 500 words or 8 obligations, info past 300 or 5 | Split the requirement into coherent areas, never into one requirement per sentence ([model](references/model.md#tests-and-scenarios)). |
39
+ | `scenario-unproven` | error, base only | A scenario you added or edited in a REQUIRED requirement has no binding. Cite it where its test, type assertion, lint entry or check proves it ([binding](references/contract.md#binding)); a test you add must catch a regression of that case. If no evidence can, the requirement takes a Known gap naming the scenario, or becomes ⚠️ ADVISORY — the owner's call. |
40
+ | `weakened` | warn, base only | A rule was removed, lowered (MUST → SHOULD), lost an absolute, gained an exception or became advisory. **Stop and ask the owner** — unless they asked for exactly this. |
41
+ | `textual-test` | warn | The test asserts on source, spec or doc text. Prefer a behavioural test, or a deterministic tool for structure. |
42
+ | `marker-hygiene` | warn | `--fix` normalises a misspelt marker. A retired `**⚠️ Unenforced:**`, or a Known gap without a tracker, exempts nothing: replace it with Advisory, a tracked Known gap, or nothing, as the [model](references/model.md#advisory-known-gap-or-neither) says, and ask the owner, because each is a reclassification. |
43
+ | `new-requirement` | info, base only | Say, in your reply, which observable failure it prevents and what cheapest evidence catches it. If there is none, it is advisory or belongs elsewhere. |
44
+ | `absolute-unproven` | info | Name the absolute's exceptions, or confirm it has none. Advisory requirements are not reported. |
45
+ | `impl-detail`, `vague-obligation`, `restating-scenario`, `duplicate-scenario`, `unbound-test` | info | Prompts for judgement, not orders. Answer them in the spec or in your reply. Never write a test just to silence one. |
46
+ | `non-ears`, `non-bdd` | info, base only | Added or edited text only: write the statement in EARS and the scenario in Given/When/Then ([model](references/model.md#tests-and-scenarios)). Never fails. |
47
+
48
+ The exact rule behind each kind is in [contract.md](references/contract.md#kinds-and-severities). The edit hook runs the per-file checks on each file you touch, with no ratchet, and feeds them back at once. Treat its message as you would this table.
49
+
50
+ ## Audit
51
+
52
+ Corpus-wide or affected-set, for corpus quality: placement, REQUIRED versus ⚠️ ADVISORY, evidence. The procedure, its parts and its verification are in [references/audit.md](references/audit.md). The output is a review file in the format of [references/review-format.md](references/review-format.md), and nothing in the specs or the code changes until the owner answers it.
53
+
54
+ Mechanical inputs:
55
+
56
+ - `steward check` (heuristic candidates)
57
+ - `steward evidence --out <dir>`: per-capability bundles, starting from the tests bound to each scenario
58
+ - `steward coverage --out <file>`: bindings, Advisory requirements and Known gaps per capability
59
+ - `steward partition --out <dir> --parts N`
60
+ - `steward index`: counts, and the citation inventory as bindings and pointers, with how many of them dangle
61
+
62
+ ## Apply
63
+
64
+ The owner answers each item in the review file. [references/apply.md](references/apply.md) processes the answers round by round:
65
+
66
+ - apply ✅
67
+ - respect ❌
68
+ - investigate a bare comment
69
+ - re-audit what changed
70
+ - append new items
71
+
72
+ `steward review status` shows what is open.
73
+
74
+ ## Align
75
+
76
+ `steward align --root A=<path> --root B=<path>` pairs the capabilities and requirements of several repositories and reports wording drift and one-sided rules. Choosing the wording is the owner's call. Once it is chosen, write it identically in every repository.
@@ -0,0 +1,18 @@
1
+ # Apply a review round
2
+
3
+ The owner has answered a review file ([review-format.md](review-format.md)). Process every item. Leave nothing half-done, and decide nothing on the owner's behalf.
4
+
5
+ 1. **Read the whole file again.** Then run `steward review status <review.md>`, which lists the open items, the comments, the accepted-but-not-applied items and the member comments of themes.
6
+ 2. **Accepted (`✅`, `✅ <comment>`).** Apply the proposal, adjusted by the comment.
7
+ - Before you touch 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
+ - A rule shared by several repositories changes identically in each; `steward align` shows the drift.
9
+ - When a change moves guidance to a new place, put it in the place `rules/agent.md` assigns, remove every copy, and reference it from where it used to live.
10
+ - Add `Applied: R<n> — <what changed>` under the item.
11
+ 3. **Rejected (`❌`, `❌ <comment>`).** Keep the rule as it is, or follow the owner's alternative instruction, and record what was done.
12
+ 4. **Comment only.** Investigate further and revise the proposal or the explanation in place. Move the owner's comment into `Previous response (R<n>): …` and reset the response to `⬜`. Never read a comment as acceptance.
13
+ 5. **Theme with member comments.** Apply the theme's verdict to the members without comments. Handle each commented member by its comment, as above.
14
+ 6. **Re-audit what changed.** Run the audit ([audit.md](audit.md)) over the affected set: the capabilities you edited, those that name them, and the moved guidance. Then run the repository's spec gate (`AGENTS.md` → Checks), or `steward check --base auto` where it names none. Append new findings under `## Round <n> — new`.
15
+ 7. **Verify.** Run the repository's own checks, as its `AGENTS.md` lists them, plus `steward review lint` and `steward review verify`. Report what failed or was skipped, with the reason.
16
+ 8. **Stop** while any item is open or carries an unresolved comment. Report the file, the counts and the decisions still needed. The loop ends only when every item is resolved, the accepted changes are in place, the repositories agree on shared rules, and a focused re-audit finds nothing material.
17
+
18
+ Never commit unless the repository's instructions say you may.
@@ -0,0 +1,57 @@
1
+ # Audit procedure
2
+
3
+ An audit asks whether the corpus holds the **right** rules with the **right** evidence. It judges by [model.md](model.md) and [criteria.md](criteria.md), places guidance by `rules/agent.md`, and produces a review file ([review-format.md](review-format.md)). Nothing in the specifications or the code changes during an audit. Whether the code conforms to the specifications is not its question; that is the repository's own conformance audit.
4
+
5
+ ## 1. Mechanical inputs
6
+
7
+ Run these for every repository in scope. With several repositories, pass `--root NAME=path` for each.
8
+
9
+ - `steward check` (add `--base auto` or `--base <ref>` for a change): heuristic candidates. They are leads, not verdicts.
10
+ - `steward index`: counts (capabilities, requirements, Advisory requirements, Known gaps, scenarios), and the citation inventory split into bindings and pointers, with how many of them dangle.
11
+ - `steward evidence --out <dir>`: one bundle per capability. A bundle holds each requirement verbatim with line numbers, the tests bound to its scenarios ([contract.md](contract.md#binding)), code citations as pointers, where its terms occur, and related requirements across capabilities and repositories.
12
+ - `steward coverage --out <file>`: bindings, Advisory requirements and Known gaps per capability.
13
+ - The repository's own gates and reports, when it has them.
14
+
15
+ ## 2. Fan out
16
+
17
+ One reader cannot hold a corpus, so partition it.
18
+
19
+ - **Parts.** Group a handful of related capabilities per part, and keep same-named capabilities from different repositories together so drift is judged in place. `steward partition --parts N` balances by size. Hand-made parts are fine when the architecture suggests better groups.
20
+ - **Sweeps.** Each sweep looks across the corpus from one angle:
21
+ - tooling and CI
22
+ - tests citing the corpus (compliance theatre)
23
+ - comments and citations
24
+ - a whole-corpus reader for duplicates, contradictions and cross-repository wording
25
+ - missing invariants
26
+ - the CI run classes
27
+ - placement against `rules/agent.md` (duplicated concerns, AGENTS.md hierarchy, scoped rules, skills)
28
+ - **Maps first.** An architecture map, an enforcement map and the owner's decision history go to every reader, so no one re-derives them.
29
+
30
+ With Claude Code's Workflow tool, run [`workflows/audit.js`](../workflows/audit.js). It takes the arguments documented at its top and returns verified, consolidated findings and themes. Without it, start one subagent per part and per sweep in waves, give each this procedure and its files, and run the verification below yourself.
31
+
32
+ ## 3. Verify every finding twice
33
+
34
+ 1. **Facts.** Is the quote verbatim at its line? Are the evidence references real, and does the code or test do what the finding claims?
35
+ 2. **Judgement.** The verifier acts as a skeptic and looks for these failures:
36
+ - **silent intent**: the finding decides an ambiguous intent without saying so. Revise it to offer options.
37
+ - **not a spec problem**: style, an ordinary bug, or speculation. Drop it.
38
+ - **compliance theatre**: the proposed verification catches no real failure. Revise or drop.
39
+ - **misplaced contract**: an internal contract moved out of the spec only because it is not user-facing. Revise.
40
+ - **wrong layer**. Revise.
41
+ - **unstated reversal** of a past owner decision. Revise to state it.
42
+ - **duplicate**. Drop the weaker one.
43
+
44
+ ## 4. Completeness
45
+
46
+ A critic looks for capabilities with neither findings nor a sound list, criteria that yielded nothing where the corpus plainly has cases, unread sources, and shared capabilities not compared. Its gaps become targeted follow-up units. Loop until a round finds nothing new; two rounds is usually enough.
47
+
48
+ ## 5. Consolidate and render
49
+
50
+ - **Merge duplicates per area.** The same rule with the same problem becomes one finding.
51
+ - **Form themes.** Several rules with one solution become one item with members.
52
+ - **Render** with `steward review render <result.json> --out <review.md> [--sections layout.json]`.
53
+ - **Check** with `steward review lint` and `steward review verify --root NAME=path …`.
54
+ - **Read every item yourself**: sharpen the wording, fix what the readers got wrong, and order the sections so decisions that others depend on come first.
55
+ - **Close with an appendix** listing the requirements judged sound, so coverage is visible.
56
+
57
+ Hand the file to the owner and stop.