@kirill.konshin/lint 0.7.3 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +160 -113
  2. package/dist/config.d.ts +103 -0
  3. package/dist/config.js +112 -0
  4. package/dist/configs/base.d.ts +1 -1
  5. package/dist/configs/nx.d.ts +1 -1
  6. package/dist/configs/nx.js +3 -8
  7. package/dist/configs/react.d.ts +3 -3
  8. package/dist/configs/react.js +6 -16
  9. package/dist/configs/storybook.d.ts +3 -3
  10. package/dist/configs/storybook.js +4 -9
  11. package/dist/configs/tailwind.d.ts +6 -25
  12. package/dist/configs/tailwind.js +3 -64
  13. package/dist/configs/testing.d.ts +1 -1
  14. package/dist/configs/testing.js +3 -15
  15. package/dist/configs/turbo.d.ts +2 -2
  16. package/dist/configs/turbo.js +4 -6
  17. package/dist/configs/typescriptTypeAware.d.ts +1 -1
  18. package/dist/gates.d.ts +72 -0
  19. package/dist/gates.js +132 -0
  20. package/dist/index.d.ts +15 -51
  21. package/dist/index.js +16 -14
  22. package/dist/lib.d.ts +1 -1
  23. package/dist/lib.js +1 -1
  24. package/dist/lintPrepare.d.ts +75 -28
  25. package/dist/lintPrepare.js +243 -35
  26. package/dist/testColocation.js +1 -1
  27. package/dist/vitePlus.d.ts +8 -18
  28. package/dist/vitePlus.js +40 -47
  29. package/package.json +7 -4
  30. package/rules/agent.md +1 -0
  31. package/rules/auth.md +3 -3
  32. package/rules/db.md +6 -9
  33. package/rules/expo.md +2 -0
  34. package/rules/github.md +1 -1
  35. package/rules/gitlab.md +1 -1
  36. package/rules/i18n.md +3 -0
  37. package/rules/monorepo-turbo-nx.md +38 -4
  38. package/rules/mui.md +8 -18
  39. package/rules/nextjs.md +13 -13
  40. package/rules/npm-yarn.md +28 -118
  41. package/rules/nx.md +1 -1
  42. package/rules/playwright.md +1 -1
  43. package/rules/react.md +7 -32
  44. package/rules/tailwind.md +9 -47
  45. package/rules/testing.md +2 -2
  46. package/rules/turbo.md +1 -1
  47. package/rules/typescript.md +6 -2
  48. package/rules/ui-kit.md +6 -0
  49. package/rules/vite.md +1 -1
  50. package/skills/lint-db/SKILL.md +23 -0
  51. package/skills/lint-electron/SKILL.md +9 -6
  52. package/skills/lint-github/SKILL.md +15 -8
  53. package/skills/lint-gitlab/SKILL.md +20 -5
  54. package/skills/lint-migrate/SKILL.md +18 -2
  55. package/skills/lint-mui/SKILL.md +28 -0
  56. package/skills/lint-nextjs/SKILL.md +53 -16
  57. package/skills/lint-npm-yarn/SKILL.md +126 -0
  58. package/skills/lint-repo/SKILL.md +12 -12
  59. package/skills/lint-tailwind/SKILL.md +53 -0
  60. package/skills/lint-webstorm/SKILL.md +3 -3
  61. package/skills/lint-worktree/SKILL.md +25 -9
  62. package/skills/spec-author/SKILL.md +2 -2
  63. package/skills/spec-steward/SKILL.md +1 -1
  64. package/skills/spec-steward/references/apply.md +1 -1
  65. package/skills/spec-steward/references/contract.md +2 -2
  66. package/skills/spec-steward/references/model.md +2 -2
  67. package/skills/spec-steward/references/review-format.md +4 -4
  68. package/skills/spec-steward/references/wiring.md +2 -2
  69. package/skills/spec-steward/references/worker.md +1 -1
  70. package/skills/spec-tools/SKILL.md +2 -2
  71. package/skills/spec-tools/references/rules/common.md +1 -1
  72. package/skills/spec-tools/references/rules/spec-steward.md +1 -1
  73. package/skills/spec-tools/scripts/cli.js +2 -2
  74. package/skills/spec-verify/SKILL.md +1 -1
@@ -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; both read `tailwind` from `lint.config.ts`
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`; trace detection with `LINT_DEBUG=1 vp lint` (or `LINT_DEBUG=1 eslint .`)
39
+ - Several entry CSS candidates are ALWAYS a HARD ERROR (a silent skip is hard to notice)
40
+ - pass `cssConfigPath` in `lint.config.ts` to pick one (Vite+: the only fix, it ignores nested `lint` blocks) OR
41
+ - ESLint only: create a leaf `eslint.config.mjs` per app with its own `cssConfigPath` (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 `lint.config.ts`:
44
+
45
+ ```ts
46
+ import { defineLintConfig } from '@kirill.konshin/lint/config';
47
+
48
+ export default defineLintConfig({
49
+ tailwind: {
50
+ cssConfigPath: './src/styles/tailwind.css', // MANDATORY, relative to the workspace 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 the `webstorm` rule, list every discrepancy, ask before fixing:
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
@@ -44,7 +44,7 @@ Compare the project's `.idea` files with the templates below and the `webstorm`
44
44
 
45
45
  # Vite+: Oxc plugin
46
46
 
47
- When the project uses `vite-plus`: the [Oxc plugin](https://plugins.jetbrains.com/plugin/27061-oxc) runs `vp lint --lsp` / `vp fmt --lsp` (AUTOMATIC mode finds `vite-plus`), so the `vite.config.ts` blocks apply. Prettier is disabled and `.idea/jsLinters/eslint.xml` deleted. The plugin stores booleans as attributes while the Vite+ docs write `<option>` - keep both; the IDE rewrites the file in its own form on save. Ask the user to confirm Settings → Tools → Oxc after reopening.
47
+ When the project uses `vite-plus`: the [Oxc plugin](https://plugins.jetbrains.com/plugin/27061-oxc) runs `vp lint --lsp` / `vp fmt --lsp` (AUTOMATIC mode finds `vite-plus`), so the Vite+ config applies (`vite.config.ts`, with the blocks from the `vitePlus` key of `lint.config.ts`). Prettier is disabled and `.idea/jsLinters/eslint.xml` deleted. The plugin stores booleans as attributes while the Vite+ docs write `<option>` - keep both; the IDE rewrites the file in its own form on save. Ask the user to confirm Settings → Tools → Oxc after reopening.
48
48
 
49
49
  `.idea/externalDependencies.xml` (required plugin; un-ignore it if `.idea` is gitignored: `!.idea/externalDependencies.xml`):
50
50
 
@@ -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 the `webstorm` rule.
152
+ Excluded folders follow the baseline of [rules/webstorm.md](../../rules/webstorm.md).
153
153
 
154
154
  ## Configure `.idea/.gitignore`:
155
155
 
@@ -1,10 +1,11 @@
1
1
  ---
2
2
  name: lint-worktree
3
- description: Describes how to work with GIT Worktrees
3
+ description: Git worktrees inside the main checkout (`.worktrees`, Claude Code's `.claude/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
- - 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
6
+ - Prefer creating worktrees inside the main repo in `.worktrees` directory; Claude Code creates its worktrees in `.claude/worktrees`
7
+ - Each worktree folder has to be gitignored (`.gitignore` or the shared `.git/info/exclude`) and marked as excluded in the main checkout's `.idea/%projectName%.iml` (`<excludeFolder url="file://$MODULE_DIR$/.claude/worktrees" />`)
8
+ - Without the exclusion, the main project indexes a second copy of every source and `node_modules`, and its save actions reformat the worktree's files
8
9
 
9
10
  # Git Worktrees & JetBrains IDEA / WebStorm
10
11
 
@@ -14,15 +15,30 @@ description: Describes how to work with GIT Worktrees
14
15
  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
16
  2. Point `.idea/modules.xml` at the renamed file.
16
17
  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
18
  - Keep the rename local, and NEVER commit it or merge it back:
19
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
20
  - Ignore the renamed file in the shared `.git/info/exclude` with the pattern `.idea/%projectName% *.iml`.
21
21
  - A **tracked** `.idea/modules.xml` or `.idea/.name`: run `git update-index --skip-worktree` on it.
22
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
+ - A worktree that has both the original `.iml` and a renamed copy: do the `skip-worktree` step on the original, then delete it.
23
24
  - 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.
25
+
26
+ # Attaching a Worktree to the Main Project
27
+
28
+ - Attaching edits tracked files of the main checkout:
29
+ - `.idea/modules.xml` gets an entry for the worktree's `.iml`; attaching can replace the main checkout's own entry: keep both, then reload the project
30
+ - `.idea/%projectName%.iml` gets `<orderEntry type="module" module-name="%projectName% %Branch Title%" />`
31
+ - `.idea/vcs.xml` can get `<mapping directory="" vcs="Git" />` instead of `$PROJECT_DIR$`
32
+ - Keep these edits local, the same as the rename: stage only the real edits to these files (e.g. a new `excludeFolder`), then `git update-index --skip-worktree` them
33
+ - To stage part of a file without `git add -p`: `git hash-object -w` the wanted content, then `git update-index --cacheinfo 100644,<blob>,<path>`
34
+ - Verify with `git status --short .idea` in the main checkout: only the staged edits are listed
35
+ - A worktree inside the main checkout shows as a module node inside the main tree, under its excluded folder, never as a top-level tree; for a top-level tree, create the worktree outside the main checkout (for Claude Code: its "Worktree location" setting; do not change it without the user's approval)
36
+ - After the worktree is detached or removed: `git update-index --no-skip-worktree` the main checkout's files, then `git checkout -- <files>`
37
+
38
+ # Before a Rebase, Merge or Checkout
39
+
40
+ In each checkout, for tracked files marked above that the operation updates:
41
+
42
+ 1. Rename the `.iml` back and run `git update-index --no-skip-worktree` on every marked file.
43
+ 2. Restore them with `git checkout -- <files>`.
44
+ 3. Redo the rename and the marks afterwards.
@@ -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(spec-steward:*), Bash(yarn openspec:*), Bash(yarn spec-tools:*), Bash(yarn spec-steward:*), Bash(npx openspec:*), Bash(npx spec-tools:*), Bash(npx spec-steward:*), Bash(git diff*), Bash(git log*), Read, Edit, Write, Glob, Grep
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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-steward
3
- description: Guard, audit and repair an OpenSpec specification corpus — whether these are the right rules, in the right place, with the right evidence; it proposes spec changes and never fails a build. Use when auditing specs for corpus quality (the whole corpus, a change, or one capability), producing or processing a spec review file (the YAML review `.spec-audit/spec-review.yaml`, where the owner answers each item's `decision` with ✅ / ❌ / a comment), 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-tools 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 `spec-verify` skill does. Writing a rule is the `/spec-author` command.
3
+ description: Guard, audit and repair an OpenSpec specification corpus - are these the right rules, in the right place, with the right evidence; it proposes spec changes and never fails a build. Use when auditing spec corpus quality, processing a spec review file (`.spec-audit/spec-review.yaml`), aligning rules shared by several repositories, wiring the spec guard into a repository, or when `spec-tools steward check` or the edit hook reports a finding. Not for code conformance (the `spec-verify` skill) or for writing a rule (the `spec-author` skill).
4
4
  ---
5
5
 
6
6
  # Spec steward
@@ -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 `rules/agent.md` tells, remove each copy, and reference it from its old place.
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.mjs` proves the cases below.
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
 
@@ -35,7 +35,7 @@ A citation of a scenario's anchor binds the scenario only where it sits in one o
35
35
  | In a test file (a JavaScript or TypeScript `*.test.*`, `*.spec.*` or `*.test-d.*` file, a file under `__tests__/` or `e2e/`, or a Python or Go test file), inside a `describe`, `it`, `test`, `suite` or `bench` call, with any `.only`, `.skip`, `.concurrent`, `.sequential`, `.todo`, `.each(…)`, `.for(…)`, `.runIf(…)`, `.skipIf(…)` or `.fails` chain, and Playwright's `test.describe`, `test.step`, `.serial`, `.parallel`, `.fixme` and `.fail`; in a Python test file, inside a `test_…` function or a `Test…` class; in a Go test file, inside a `Test…` function | yes |
36
36
  | In a test file, in the comment run directly above such a call or function (in Python, its decorators too), with no blank line between | yes |
37
37
  | In a test file, on a type assertion — an `Expect<…>` type alias, or an `expectTypeOf(…)` or `assertType(…)` call — at the top level or inside a block | yes |
38
- | In a lint configuration — `eslint.config.{js,mjs,cjs,ts,mts,cts}`, `vite.config.{js,mjs,cjs,ts,mts,cts}` (Vite+) or `yarn.config.cjs` — anywhere | yes |
38
+ | In a lint configuration — `eslint.config.{js,mjs,cjs,ts,mts,cts}`, `vite.config.{js,mjs,cjs,ts,mts,cts}` (Vite+), `lint.config.{js,mjs,cjs,ts,mts,cts}` (`@kirill.konshin/lint`) or `yarn.config.cjs` — anywhere | yes |
39
39
  | In a file matching a `binds` glob the repository declares — `"spec-steward": { "binds": [...] }` in its root `package.json`, or `--binds <glob>` — (a check script, a Dockerfile, a CI configuration), anywhere | yes |
40
40
  | Anywhere else in a test file: its header, a fixture, a helper | no — it binds nothing and fails nothing |
41
41
  | Code, configuration, YAML, a Dockerfile or a document that no `--binds` glob matches | no — it is a pointer |
@@ -1,6 +1,6 @@
1
1
  # The specification model
2
2
 
3
- Where a piece of guidance lives is decided by `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).
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 `rules/agent.md`; then the decision test:
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 accountId, rcAccountId, rcRequestId and rcUserId…
20
- location: 'SHOP openspec/specs/system-overview/logging/spec.md:47'
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: 'SHOP openspec/specs/apps/runtime/spec.md:88'
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: 'SHOP openspec/specs/apps/db/spec.md:12'
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.
@@ -5,14 +5,14 @@ A skill is discovered at the agent's discretion, so it cannot be the only thing
5
5
  | Point | What it does | Placed by |
6
6
  | --- | --- | --- |
7
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` |
8
+ | Skill `.agents/skills/spec-steward` (+ `.claude/skills`) | The procedures, the model, the contract and the scripts. | `lint-prepare` (through the `skills` CLI) |
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 `spec-verify` 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 |
12
12
 
13
13
  These five points keep to the placement rules:
14
14
 
15
- - Nothing restates `rules/agent.md` or the repository's own rules.
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
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  This file tells how one worker of the corpus-quality audit runs. `spec-tools workers --audit spec-steward` starts one worker per unit of the scope. Its brief names the unit, the files to read and the findings file to write. The procedure around the workers is [audit.md](audit.md).
4
4
 
5
- What to judge is in the judging rules: [`common.md`](../../spec-tools/references/rules/common.md), then [`spec-steward.md`](../../spec-tools/references/rules/spec-steward.md). How a specification is written is [model.md](model.md). Where guidance belongs is the placement guide, `rules/agent.md` of this package. Read them before you judge.
5
+ What to judge is in the judging rules: [`common.md`](../../spec-tools/references/rules/common.md), then [`spec-steward.md`](../../spec-tools/references/rules/spec-steward.md). How a specification is written is [model.md](model.md). Where guidance belongs is the placement guide, [rules/agent.md](../../../rules/agent.md) of this package. Read them before you judge.
6
6
 
7
7
  The audit is read-only. You write your findings file and nothing else. Your tools are Read, Glob, Grep, Write and the read-only git commands. Other commands are denied and only cost a turn.
8
8
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-tools
3
- description: The machinery around both audits — set up and run the `spec-tools` CLI of `@kirill.konshin/lint` in an OpenSpec repository — the change gates and workflow-evidence gate beside spec-steward's corpus gate, the requirement-level specification diff, the `spec-verify` code-conformance audit (run class, scope, workers, merge, verdict), and the glue a CI pipeline runs around a headless AI review (verdict gate, merge-request comment, HTML reports). Use when wiring these into a repository or its pipeline, when a `spec-tools` command fails or its output needs reading, or when deciding which run class an audit is.
3
+ description: Set up and run the `spec-tools` CLI of `@kirill.konshin/lint` in an OpenSpec repository - change gates, workflow-evidence gate, specification diff, runs of the `spec-verify` audit, and the CI glue around a headless AI review. Use when wiring spec-tools into a repository or its pipeline, when a `spec-tools` command fails or its output needs reading, or when choosing the run class of an audit.
4
4
  ---
5
5
 
6
6
  # spec-tools
@@ -35,7 +35,7 @@ Run them through the package manager (`yarn spec-tools gates`), the bin (`node_m
35
35
 
36
36
  ## Setting a repository up
37
37
 
38
- 1. Pin `@kirill.konshin/lint`; `lint-prepare` links the `spec-steward`, `spec-tools` and `spec-verify` skills.
38
+ 1. Pin `@kirill.konshin/lint`; `lint-prepare` installs the `spec-steward`, `spec-tools` and `spec-verify` skills.
39
39
  2. Declare what binds beyond spec-steward's defaults once, in the root `package.json`: `"spec-steward": { "binds": ["scripts/checks/**", "**/*.Dockerfile", ".gitlab-ci.yml"] }`.
40
40
  3. List the gates in the repository's `AGENTS.md` checks: `openspec validate --strict --all`, `spec-tools gates`, and after a requirement changes `spec-tools changed` with `/spec-verify changed` and `spec-tools diff`.
41
41
  4. Ignore the generated files with one `.gitignore` line, `.spec-audit/`: every file the tools and the audits write is under it — YAML data, the Markdown and HTML reports, `claude.jsonl`, the job logs. In CI, publish `.spec-audit/` as each audit job's artifacts path.
@@ -1,6 +1,6 @@
1
1
  # Judging rules: common
2
2
 
3
- These rules tell what a finding is, how severe it is, and how sure you are of it. They apply to every audit that spec-tools runs: spec-verify, its judge, spec-steward and check-entity-hacks. The skill and the tool tell how a run works.
3
+ These rules tell what a finding is, how severe it is, and how sure you are of it. They apply to every audit that spec-tools runs: spec-verify, its judge and spec-steward. The skill and the tool tell how a run works.
4
4
 
5
5
  ## Evidence
6
6
 
@@ -7,7 +7,7 @@ This audit judges if the specification holds the correct rules with the correct
7
7
  ## Items to report
8
8
 
9
9
  1. A REQUIRED rule that must be ⚠️ Advisory (see Severity).
10
- 2. A rule that belongs in `AGENTS.md`, a scoped rule, a skill, a command, the OpenSpec configuration or a README. The placement guide is `rules/agent.md`.
10
+ 2. A rule that belongs in `AGENTS.md`, a scoped rule, a skill, a command, the OpenSpec configuration or a README. The placement guide is [rules/agent.md](../../../../rules/agent.md).
11
11
  3. A rule that a deterministic tool can enforce better than an AI audit.
12
12
  4. A rule that causes tests of low value or artificial tests.
13
13
  5. A rule whose tests satisfy the wording while failing to protect the intent.
@@ -7689,7 +7689,7 @@ var init_citations = __esmMin((() => {
7689
7689
  CITE = /((?:\.{1,2}\/)*(?:[\w@.-]+\/)*?openspec\/specs\/[\w./-]*?spec\.md)(?:#([\w-]+))?/g;
7690
7690
  SKIP = /(?:^|\/)(?:node_modules|dist|build|coverage|\.git|\.nx|\.yarn|\.yalc|\.turbo|\.next|\.docusaurus|\.eve)(?:\/|$)|^openspec\/changes\/|(?:^|\/)spec\.md$/;
7691
7691
  TEST_FILE = /(?:^|\/)(?:__tests__|e2e)\/|\.(?:test|spec|test-d)\.[cm]?[jt]sx?$|(?:^|\/)test_[^/]+\.py$|_test\.(?:py|go)$/;
7692
- LINT_CONFIG = /(?:^|\/)(?:(?:eslint|vite)\.config\.[cm]?[jt]s|yarn\.config\.cjs)$/;
7692
+ LINT_CONFIG = /(?:^|\/)(?:(?:eslint|vite|lint)\.config\.[cm]?[jt]s|yarn\.config\.cjs)$/;
7693
7693
  isTestFile = (file) => TEST_FILE.test(file) && !isDoc(file);
7694
7694
  isLintConfig = (file) => LINT_CONFIG.test(file);
7695
7695
  anchorCache = /* @__PURE__ */ new Map();
@@ -9184,7 +9184,7 @@ function wireCli(opts, root) {
9184
9184
  const labels = {
9185
9185
  agents: "AGENTS.md routes to spec-steward",
9186
9186
  rule: ".agents/rules/openspec.md (or .claude/rules) is linked by lint-prepare",
9187
- skill: ".agents/skills/spec-steward (or .claude/skills) is linked by lint-prepare",
9187
+ skill: ".agents/skills/spec-steward (or .claude/skills) is installed by lint-prepare",
9188
9188
  hook: ".claude/settings.json runs the edit hook",
9189
9189
  opsx: `openspec/config apply/archive guidance points at the repository's spec gate (${GATE_POINTER})`
9190
9190
  };
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-verify
3
- description: Audit whether the code satisfies the intent of the OpenSpec specifications; its verdict gates CI. Checks what no tool can - cross-capability contradiction, code that does not satisfy a requirement's intent, whether a bound test asserts its scenario, and gaps nobody recorded. It audits code conformance only; corpus quality is the spec-steward skill's audit. The judging rules are in the spec-tools skill's references/rules/ (common.md, spec-verify.md). Readers only judge; each writes .spec-audit/parts/findings/part-<n>-<reader>.yaml and `spec-tools report` renders .spec-audit/spec-verify.md. Interactively, run `spec-tools audit`, then summarize the report and ask the operator what to do. After changing a capability, `/spec-verify changed` judges what changed.
3
+ description: Audit whether the code satisfies the intent of the OpenSpec specifications; its verdict gates CI. Finds what no tool can - cross-capability contradictions, code that misses a requirement's intent, bound tests that do not assert their scenario, gaps nobody recorded. Use for a code-conformance audit (`spec-tools audit`) or after changing a capability (`/spec-verify changed`). Not for corpus quality (the `spec-steward` skill).
4
4
  model: claude-haiku-5-5
5
5
  effort: high
6
6
  ---