@kirill.konshin/lint 0.5.3 → 0.5.5
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/README.md +10 -5
- package/dist/configs/testing.d.ts.map +1 -1
- package/dist/configs/testing.js +10 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/lintPrepare.d.ts +20 -21
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +53 -62
- package/dist/restrictions.d.ts +23 -0
- package/dist/restrictions.d.ts.map +1 -0
- package/dist/restrictions.js +24 -0
- package/package.json +1 -1
- package/rules/agent.md +5 -4
- package/rules/github.md +0 -76
- package/rules/gitlab.md +0 -72
- package/rules/nextjs.md +2 -55
- package/rules/storybook.md +2 -0
- package/rules/tailwind.md +1 -1
- package/rules/webstorm.md +6 -214
- package/skills/lint-github/SKILL.md +78 -0
- package/skills/lint-gitlab/SKILL.md +76 -0
- package/skills/lint-nextjs/SKILL.md +59 -0
- package/skills/{lint-repo.md → lint-repo/SKILL.md} +1 -1
- package/skills/lint-webstorm/SKILL.md +201 -0
- package/skills/lint-worktree/SKILL.md +28 -0
- package/skills/spec-steward/SKILL.md +1 -1
- package/skills/spec-steward/references/contract.md +4 -4
- package/skills/spec-steward/references/model.md +1 -1
- package/skills/spec-steward/references/wiring.md +2 -2
- package/skills/spec-steward/scripts/lib/align.mjs +7 -6
- package/skills/spec-steward/scripts/lib/checks.mjs +6 -1
- package/skills/spec-steward/scripts/lib/corpus.mjs +4 -7
- package/skills/spec-steward/scripts/lib/coverage.mjs +2 -3
- package/skills/spec-steward/scripts/lib/evidence.mjs +0 -1
|
@@ -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="{ "inspectPort": null, "emmetCompletions": false, "classAttributes": ["class", "className", "activeClassName", "disabledClassName", "ngClass", "class:list"], "classFunctions": [], "codeActions": true, "codeLens": true, "hovers": true, "suggestions": true, "validate": true, "colorDecorators": true, "rootFontSize": 16, "lint": { "cssConflict": "warning", "invalidApply": "error", "invalidScreen": "error", "invalidVariant": "error", "invalidConfigPath": "error", "invalidTailwindDirective": "error", "invalidSourceDirective": "error", "recommendedVariantOrder": "warning", "usedBlocklistedClass": "warning" }, "showPixelEquivalents": true, "includeLanguages": { "ftl": "html", "jinja": "html", "jinja2": "html", "smarty": "html", "tmpl": "gohtml", "cshtml": "html", "vbhtml": "html", "razor": "html" }, "files": { "exclude": [ "**/.git/**", "**/.hg/**", "**/.svn/**", "**/node_modules/**", "**/.yarn/**", "**/.venv/**", "**/venv/**", "**/.next/**", "**/.parcel-cache/**", "**/.svelte-kit/**", "**/.turbo/**", "**/__pycache__/**" ] }, "experimental": { "configFile": null, "classRegex": [ "Classes\\s*=\\s*['\"`]([^'\"`]*?)['\"`]", "['\"`]([^'\"`]*?)['\"`]", "Styles\\s*=\\s*['\"`]([^'\"`]*?)['\"`]", "['\"`]([^'\"`]*?)['\"`]" ] } }" />
|
|
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.
|
|
@@ -37,7 +37,7 @@ Where the repository's `AGENTS.md` names a spec gate in its Checks list, such as
|
|
|
37
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
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
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. |
|
|
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. In a hand-back, map each finding to the decision that authorised it (a review item, a ticket, the owner's word) and list only the unmatched ones for a decision; a verbatim move is already reported as a rename. |
|
|
41
41
|
| `textual-test` | warn | The test asserts on source, spec or doc text. Prefer a behavioural test, or a deterministic tool for structure. |
|
|
42
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
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. |
|
|
@@ -51,14 +51,14 @@ Cases:
|
|
|
51
51
|
|
|
52
52
|
## Markers
|
|
53
53
|
|
|
54
|
-
There are exactly two markers. Each stands on a line of its own: the Advisory line in the requirement's statement, directly under its heading, and a Known gap line in the statement
|
|
54
|
+
There are exactly two markers. Each stands on a line of its own: the Advisory line in the requirement's statement, directly under its heading, and a Known gap line in the statement.
|
|
55
55
|
|
|
56
56
|
| Marker | Meaning |
|
|
57
57
|
| --- | --- |
|
|
58
58
|
| `**⚠️ Advisory:** <why review is its evidence>` | The requirement is ADVISORY. It keeps its RFC 2119 keywords and is exempt from the scenario ratchet and from `absolute-unproven`. Coverage reports it as `advisory`, and the evidence JSON classes it `advisory`. Marking an existing requirement Advisory is reported as `weakened` ("newly marked advisory"). It qualifies the whole requirement, so a requirement that mixes a contract with guidance is split. |
|
|
59
|
-
| `**⚠️ Known gap (<tracker>):** <what is missing>` | Behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. `<tracker>` is required text: a ticket key (`EVAA-34696`), a tickets-page id, or an open `openspec/changes/<name>` folder. Steward checks only that it is present: any non-empty text inside the parentheses counts and is not validated, so a placeholder counts until it is replaced. In the statement, the line records the gap and exempts nothing, unless it names scenarios of its requirement by title after `exempts`, each in quotes (`exempts scenario 'A'`, `exempts scenarios 'A' and 'B'`; double quotes, curly quotes, `_…_` and `*…*` are read too). Exactly the named scenarios are then exempt from the scenario ratchet.
|
|
59
|
+
| `**⚠️ Known gap (<tracker>):** <what is missing>` | Behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. `<tracker>` is required text: a ticket key (`EVAA-34696`), a tickets-page id, or an open `openspec/changes/<name>` folder. Steward checks only that it is present: any non-empty text inside the parentheses counts and is not validated, so a placeholder counts until it is replaced. In the statement, the line records the gap and exempts nothing, unless it names scenarios of its requirement by title after `exempts`, each in quotes (`exempts scenario 'A'`, `exempts scenarios 'A' and 'B'`; double quotes, curly quotes, `_…_` and `*…*` are read too). Exactly the named scenarios are then exempt from the scenario ratchet. Coverage lists every gap with its tracker. |
|
|
60
60
|
|
|
61
|
-
Retired spellings are `**⚠️ Unenforced:**` and `**⚠️ Known gap:**` without a tracker. Each is reported as `marker-hygiene` and grants no exemption. So is a marker inside a line rather than on a line of its own, and an Advisory line inside a scenario. A misspelt marker (wrong case, missing emoji or bold) is reported as `marker-hygiene`, and `--fix` normalises it.
|
|
61
|
+
Retired spellings are `**⚠️ Unenforced:**` and `**⚠️ Known gap:**` without a tracker. Each is reported as `marker-hygiene` and grants no exemption. So is a marker inside a line rather than on a line of its own, and an Advisory or Known gap line inside a scenario. A misspelt marker (wrong case, missing emoji or bold) is reported as `marker-hygiene`, and `--fix` normalises it.
|
|
62
62
|
|
|
63
63
|
Cases:
|
|
64
64
|
|
|
@@ -179,7 +179,7 @@ Exit 2 on an empty listing keeps a broken checkout from passing a scan that read
|
|
|
179
179
|
```
|
|
180
180
|
|
|
181
181
|
- `class` is `advisory` when the requirement carries the Advisory marker, else `required`.
|
|
182
|
-
- `gaps` lists each Known gap line
|
|
182
|
+
- `gaps` lists each Known gap line under the requirement that carries a tracker; `exempts` lists the slugs of the scenarios it names, empty when it names none.
|
|
183
183
|
- `bindings` are the citations that [bind](#binding) a scenario or the requirement. `kind` is `test` for a test-file binding, and `file` for a lint configuration or a `--binds` file. `title` is the bound test's title, or `null`; `window` is the line range of the bound block.
|
|
184
184
|
- `pointers` are every other citation of the requirement or its scenarios.
|
|
185
185
|
- `terms` are the requirement's own distinctive terms, with every hit in non-test sources after comments are stripped. Line numbers are kept.
|
|
@@ -30,7 +30,7 @@ A REQUIRED requirement stating an absolute names its exceptions, or has none; on
|
|
|
30
30
|
A requirement is REQUIRED unless a marker says otherwise. The exact spellings, and what each exempts, are in [contract.md](contract.md#markers).
|
|
31
31
|
|
|
32
32
|
- **⚠️ Advisory** — permanent guidance whose only evidence is review, such as a design direction. Its line says why review is its evidence, and its RFC 2119 keywords stay. The marker qualifies the whole requirement, so a requirement that mixes a contract with guidance is split, and the contract half stays REQUIRED. Marking an existing requirement Advisory weakens it, so the owner confirms it.
|
|
33
|
-
- **⚠️ Known gap (<tracker>)** — behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. The line says what is missing (for missing evidence, the missing rung) and names what tracks it: a ticket, a tickets-page entry or an open change.
|
|
33
|
+
- **⚠️ Known gap (<tracker>)** — behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. The line says what is missing (for missing evidence, the missing rung) and names what tracks it: a ticket, a tickets-page entry or an open change. It sits under the requirement statement and names by title the scenarios it exempts; inside a scenario's block it grants nothing. A gap is never restated as a scenario, and a scenario that a gap conditions states that condition.
|
|
34
34
|
- **Neither** — a test (an end-to-end test included), a type assertion, a lint entry or a deterministic check that CI runs proves the rule. It stays REQUIRED and unmarked.
|
|
35
35
|
|
|
36
36
|
## The evidence ladder — cheapest first
|
|
@@ -4,8 +4,8 @@ A skill is discovered at the agent's discretion, so it cannot be the only thing
|
|
|
4
4
|
|
|
5
5
|
| Point | What it does | Placed by |
|
|
6
6
|
| --- | --- | --- |
|
|
7
|
-
| Scoped rule `.agents/rules/openspec.md` (+ `.claude/rules
|
|
8
|
-
| Skill `.agents/skills/spec-steward` (+ `.claude/skills
|
|
7
|
+
| Scoped rule `.agents/rules/openspec.md` (+ `.claude/rules`) | Hard constraints, loaded when the agent touches `openspec/**`. | `lint-prepare` (`@kirill.konshin/lint`) |
|
|
8
|
+
| Skill `.agents/skills/spec-steward` (+ `.claude/skills`) | The procedures, the model, the contract and the scripts. | `lint-prepare` |
|
|
9
9
|
| Edit hook in `.claude/settings.json` | Runs `steward hook` after every Edit/Write/MultiEdit and feeds findings back to the agent at once — only for what the edit changed, with no ratchet. | `steward wire --fix` |
|
|
10
10
|
| Routing line in `AGENTS.md` | Tells every agent, Codex included, where the guard lives, and that corpus-quality audits use this skill while code conformance is the repository's own audit. | You, beside the specification-driven convention; `wire --fix` prints the line. |
|
|
11
11
|
| OPSX operation guidance in `openspec/config.yaml` | One narrow line each for `apply` and `archive`: run the repository's spec gate (AGENTS.md → Checks); a `weakened` finding stops the flow. | `steward wire --fix`, when the file has OpenSpec's standard shape |
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
// @ts-check
|
|
2
2
|
/**
|
|
3
3
|
* Rules shared by several repositories, compared: capabilities pair by path or by leaf name, requirements by anchor or
|
|
4
|
-
* by
|
|
4
|
+
* by statement. A rule is its name and statement; its scenarios are each repository's own, so a scenario only one
|
|
5
|
+
* repository has is not drift. Reports identical, drifted and one-sided rules; choosing the wording stays with the owner.
|
|
5
6
|
*/
|
|
6
7
|
import { loadCorpus } from './corpus.mjs';
|
|
7
8
|
import { jaccard, normalize, words } from './util.mjs';
|
|
@@ -11,8 +12,8 @@ import { jaccard, normalize, words } from './util.mjs';
|
|
|
11
12
|
* @typedef {import('./corpus.mjs').Requirement} Requirement
|
|
12
13
|
*/
|
|
13
14
|
|
|
14
|
-
/**
|
|
15
|
-
const
|
|
15
|
+
/** The rule's own words: its statement, without its markers and scenarios, normalized. @param {Requirement} r */
|
|
16
|
+
const statement = (r) => normalize(r.statement);
|
|
16
17
|
|
|
17
18
|
/**
|
|
18
19
|
* Word-level difference of two texts: the words only one side has, in order.
|
|
@@ -46,7 +47,7 @@ export function align(a, b) {
|
|
|
46
47
|
if (!rb) {
|
|
47
48
|
const best = cb.requirements
|
|
48
49
|
.filter((x) => !used.has(x.slug))
|
|
49
|
-
.map((x) => ({ x, s: jaccard(words(ra.
|
|
50
|
+
.map((x) => ({ x, s: jaccard(words(ra.statement), words(x.statement)) }))
|
|
50
51
|
.sort((p, q) => q.s - p.s)[0];
|
|
51
52
|
if (best && best.s >= 0.5) rb = best.x;
|
|
52
53
|
}
|
|
@@ -55,12 +56,12 @@ export function align(a, b) {
|
|
|
55
56
|
continue;
|
|
56
57
|
}
|
|
57
58
|
used.add(rb.slug);
|
|
58
|
-
const same =
|
|
59
|
+
const same = statement(ra) === statement(rb) && ra.name === rb.name;
|
|
59
60
|
reqs.push({
|
|
60
61
|
kind: same ? 'identical' : 'drift',
|
|
61
62
|
a: ra,
|
|
62
63
|
b: rb,
|
|
63
|
-
...(same ? {} : wordDiff(ra.
|
|
64
|
+
...(same ? {} : wordDiff(ra.statement, rb.statement)),
|
|
64
65
|
});
|
|
65
66
|
}
|
|
66
67
|
for (const rb of cb.requirements) if (!used.has(rb.slug)) reqs.push({ kind: 'only-b', b: rb });
|
|
@@ -203,6 +203,11 @@ function markerFindings(r) {
|
|
|
203
203
|
m.line,
|
|
204
204
|
"Advisory is the requirement's class — put it directly under the requirement heading; in a scenario it grants nothing",
|
|
205
205
|
);
|
|
206
|
+
else if (m.label === KNOWN_GAP && m.scenario)
|
|
207
|
+
warn(
|
|
208
|
+
m.line,
|
|
209
|
+
'a Known gap goes under the requirement statement and names the scenarios it exempts by title; inside a scenario it grants nothing',
|
|
210
|
+
);
|
|
206
211
|
else {
|
|
207
212
|
const canon = m.label === ADVISORY ? DEFAULT_MARKERS[0] : `**⚠️ Known gap (${m.tracker}):**`;
|
|
208
213
|
if (!m.text.startsWith(canon)) {
|
|
@@ -212,7 +217,7 @@ function markerFindings(r) {
|
|
|
212
217
|
}
|
|
213
218
|
}
|
|
214
219
|
for (const g of r.gaps)
|
|
215
|
-
if (g.named && !g.exempts.
|
|
220
|
+
if (g.named && !g.exempts.length)
|
|
216
221
|
warn(
|
|
217
222
|
g.line,
|
|
218
223
|
'names no scenario of this requirement by its title — a Known gap exempts only the scenarios it names',
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* The OpenSpec corpus as data: capabilities, requirements, scenarios, each with its line and anchor, and the two
|
|
4
4
|
* markers a requirement can carry — `**⚠️ Advisory:**` (its class) and `**⚠️ Known gap (<tracker>):**` (a gap,
|
|
5
|
-
* exempting the scenarios it names
|
|
5
|
+
* exempting the scenarios it names by title).
|
|
6
6
|
*/
|
|
7
7
|
import fs from 'node:fs';
|
|
8
8
|
import path from 'node:path';
|
|
@@ -14,8 +14,7 @@ import { slugify, stripCode, strongCount, weakCount } from './util.mjs';
|
|
|
14
14
|
* @typedef {{ kw: string, text: string, line: number }} Step
|
|
15
15
|
* @typedef {{ label: string, tracker: string | null, line: number, text: string, scenario: string | null,
|
|
16
16
|
* inline: boolean }} Marker
|
|
17
|
-
* @typedef {{ tracker: string, text: string, line: number,
|
|
18
|
-
* named: boolean }} Gap
|
|
17
|
+
* @typedef {{ tracker: string, text: string, line: number, exempts: string[], named: boolean }} Gap
|
|
19
18
|
* @typedef {{ name: string, slug: string, line: number, end: number, block: string, steps: Step[],
|
|
20
19
|
* markers: Marker[] }} Scenario
|
|
21
20
|
* @typedef {{
|
|
@@ -114,16 +113,14 @@ export function parseSpec(text, file, capability) {
|
|
|
114
113
|
const own = r.markers.filter((m) => !m.inline);
|
|
115
114
|
r.advisory = own.some((m) => m.label === ADVISORY && !m.scenario);
|
|
116
115
|
r.gaps = own
|
|
117
|
-
.filter((m) => m.label === KNOWN_GAP && m.tracker)
|
|
116
|
+
.filter((m) => m.label === KNOWN_GAP && m.tracker && !m.scenario)
|
|
118
117
|
.map((m) => {
|
|
119
118
|
const named = namedIn(m.text, r.scenarios);
|
|
120
|
-
const exempts = [...new Set([...(m.scenario ? [m.scenario] : []), ...(named ?? [])])];
|
|
121
119
|
return {
|
|
122
120
|
tracker: /** @type {string} */ (m.tracker),
|
|
123
121
|
text: m.text,
|
|
124
122
|
line: m.line,
|
|
125
|
-
|
|
126
|
-
exempts,
|
|
123
|
+
exempts: named ?? [],
|
|
127
124
|
named: named !== null,
|
|
128
125
|
};
|
|
129
126
|
});
|
|
@@ -60,14 +60,13 @@ export function coverageReport(corpus, citations) {
|
|
|
60
60
|
const scenarioBound = (/** @type {import('./corpus.mjs').Scenario} */ s) =>
|
|
61
61
|
bound.has(`${r.file}#${s.slug}`) || (r.scenarios.length === 1 && bound.has(reqKey));
|
|
62
62
|
const anyBound = bound.has(reqKey) || r.scenarios.some(scenarioBound);
|
|
63
|
-
const requirementGaps = r.gaps.filter((g) => !g.scenario);
|
|
64
63
|
if (r.advisory) totals.advisory++;
|
|
65
64
|
totals.gaps += r.gaps.length;
|
|
66
65
|
if (!r.advisory && !anyBound) totals.unboundRequirements++;
|
|
67
66
|
const status = r.advisory
|
|
68
67
|
? 'advisory'
|
|
69
|
-
:
|
|
70
|
-
? `known gap (${
|
|
68
|
+
: r.gaps.length
|
|
69
|
+
? `known gap (${r.gaps.map((g) => mdx(g.tracker)).join(', ')})`
|
|
71
70
|
: anyBound
|
|
72
71
|
? 'tested'
|
|
73
72
|
: 'no test';
|