@kirill.konshin/lint 0.5.4 → 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 CHANGED
@@ -77,6 +77,11 @@ Create `.prettierignore` file:
77
77
  .idea
78
78
  .husky
79
79
  .yarn
80
+
81
+ # OpenSpec writes these; they stay exactly as `openspec update` leaves them
82
+ .agents/skills/openspec-*
83
+ .claude/skills/openspec-*
84
+ .claude/commands/opsx
80
85
  ```
81
86
 
82
87
  https://prettier.io/docs/ignore:
@@ -329,15 +334,15 @@ The generated `AGENTS.md` has a `# Custom Rules` section at the bottom — add p
329
334
 
330
335
  In the project root, `lint-prepare`:
331
336
 
332
- - Creates real `rules/`, `commands/` and `skills/` directories in `.agents/` (canonical, cross-tool), `.claude/` (Claude Code) and `.codex/`, and only ever symlinks files into them.
337
+ - Creates real `rules/`, `commands/` and `skills/` directories in `.agents/` (canonical, cross-tool) and `.claude/` (Claude Code), and only ever symlinks files into them.
333
338
  - Links every `rules/*.md` and every skill folder (`skills/<name>/` with all its files, plus this `README.md` next to `SKILL.md` unless the skill ships one, so a skill can reference `@README.md`) into all three — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules. Links point straight at the installed package's real location (`node_modules/@kirill.konshin/lint`, or the workspace package).
334
- - Mirrors your own files from `.agents/{rules,commands,skills}/` into `.claude/` and `.codex/`; a file of yours wins over the package file at the same path.
339
+ - Mirrors your own files from `.agents/{rules,commands,skills}/` into `.claude/`; a file of yours wins over the package file at the same path.
335
340
  - Removes dead links (e.g. after renaming a file) and the links it placed before but no longer needs. Each directory gets a generated `.gitignore` listing its links, so your own files stay tracked.
336
- - Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — per rule (the package's and yours) a `## <Title>` (from the file name), its frontmatter `description` and an `@path` to its `.agents/rules/<file>` entry — and symlinks `CLAUDE.md` to it.
341
+ - Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — one entry per rule (the package's and yours): its title, frontmatter `description`, the `paths` it is scoped to and a plain link to its `.agents/rules/<file>` entry — and symlinks `CLAUDE.md` to it. The links are never `@` imports: Claude Code loads `.claude/rules` itself and honours each rule's `paths`, while an import would load every rule into every session.
337
342
 
338
343
  ### Safety checks
339
344
 
340
- Only the files `lint-prepare` knows (package files and mirrors of yours) and dead links are touched: real files are never overwritten (e.g. your own `.claude/rules/*.md`, Codex command policies in `.codex/rules/*.rules`) and nothing is written through a symlinked directory. `init`/`update` refuse to run if `CLAUDE.md` isn't a symlink. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
345
+ Only the files `lint-prepare` knows (package files and mirrors of yours) and dead links are touched: real files are never overwritten (e.g. your own `.claude/rules/*.md`) and nothing is written through a symlinked directory. `.codex/` is not touched: Codex reads `.agents/skills` and `AGENTS.md`, and the links earlier versions placed in `.codex/` stay until you delete them. `init`/`update` refuse to run if `CLAUDE.md` isn't a symlink. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
341
346
 
342
347
  ## Migration
343
348
 
@@ -1 +1 @@
1
- {"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/configs/testing.ts"],"names":[],"mappings":"AAYA,OAAO,YAAY,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAQ,MAAM,QAAQ,CAAC;AAC3C,OAAO,UAAU,MAAM,oBAAoB,CAAC;AAG5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AA6DpC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,MAAM,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAgB5F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,MAAM,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAsB9F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,CAmB5C"}
1
+ {"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/configs/testing.ts"],"names":[],"mappings":"AAYA,OAAO,YAAY,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAQ,MAAM,QAAQ,CAAC;AAC3C,OAAO,UAAU,MAAM,oBAAoB,CAAC;AAG5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AA6DpC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,MAAM,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAgB5F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,MAAM,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAgC9F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,CAmB5C"}
@@ -110,6 +110,16 @@ export function vitestConfig(option, strict = false) {
110
110
  ...vitestPlugin.configs.recommended,
111
111
  name: 'Vitest Rules',
112
112
  files: [`**/*.{test,spec}.${tsExts}`],
113
+ rules: {
114
+ ...vitestPlugin.configs.recommended.rules,
115
+ // `expectTypeOf` and `assertType` are assertions too: a type test proves its contract without a runtime
116
+ // expect. Listed here rather than through the plugin's `typecheck` setting, which makes other rules demand
117
+ // type information.
118
+ 'vitest/expect-expect': [
119
+ 'error',
120
+ { assertFunctionNames: ['expect', 'assert', 'expectTypeOf', 'assertType'] },
121
+ ],
122
+ },
113
123
  },
114
124
  {
115
125
  ...vitestPlugin.configs.env,
package/dist/index.d.ts CHANGED
@@ -15,6 +15,7 @@ export * from './configs/typescriptTypeAware.js';
15
15
  export * from './configs/unicorn.js';
16
16
  export * from './exts.js';
17
17
  export * from './lib.js';
18
+ export * from './restrictions.js';
18
19
  export * from './lintStaged.js';
19
20
  export * from './prettier.js';
20
21
  type ProjectServiceOptions = Exclude<NonNullable<TsParserOptions['projectService']>, boolean>;
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,IAAI,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAgB1F,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kCAAkC,CAAC;AACjD,cAAc,sBAAsB,CAAC;AAErC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAE9B,KAAK,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAE9F,MAAM,MAAM,aAAa,GAAG;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG;IACtC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAC1C,aAAa,CAAC,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,aAAa,GACxC,IAAI,CACA,qBAAqB,EACrB,qBAAqB,GAAG,iEAAiE,CAC5F,GAAG;IACA,eAAe,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;CACxD,CAAC;AAEN,MAAM,MAAM,oBAAoB,GAC5B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,CAAC,EAAE,IAAI,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F,MAAM,MAAM,WAAW,GAAG;IACtB,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,IAAI,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IACpC,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAChC,EAAE,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACrC,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,aAAa,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CAClD,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAClC,OAAO,GAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAM,GAC9F,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAgD1B"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,IAAI,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAgB1F,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kCAAkC,CAAC;AACjD,cAAc,sBAAsB,CAAC;AAErC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAE9B,KAAK,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAE9F,MAAM,MAAM,aAAa,GAAG;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG;IACtC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAC1C,aAAa,CAAC,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,aAAa,GACxC,IAAI,CACA,qBAAqB,EACrB,qBAAqB,GAAG,iEAAiE,CAC5F,GAAG;IACA,eAAe,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;CACxD,CAAC;AAEN,MAAM,MAAM,oBAAoB,GAC5B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,CAAC,EAAE,IAAI,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F,MAAM,MAAM,WAAW,GAAG;IACtB,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,IAAI,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IACpC,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAChC,EAAE,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACrC,SAAS,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACvC,aAAa,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CAClD,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAClC,OAAO,GAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAM,GAC9F,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAgD1B"}
package/dist/index.js CHANGED
@@ -25,6 +25,7 @@ export * from './configs/typescriptTypeAware.js';
25
25
  export * from './configs/unicorn.js';
26
26
  export * from './exts.js';
27
27
  export * from './lib.js';
28
+ export * from './restrictions.js';
28
29
  export * from './lintStaged.js';
29
30
  export * from './prettier.js';
30
31
  /**
@@ -3,11 +3,10 @@
3
3
  * @kirill.konshin/lint
4
4
  *
5
5
  * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
- * `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
6
+ * `.agents` (canonical, cross-tool) and `.claude` (Claude Code), and fills them with
7
7
  * file symlinks only: package rules and skills (every file a skill folder ships, plus the package
8
- * README.md next to its SKILL.md, so a skill can reference `@README.md`) go into all three, pointing
9
- * straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`
10
- * and `.codex`. It also
8
+ * README.md next to its SKILL.md, so a skill can reference `@README.md`) go into both, pointing
9
+ * straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`. It also
11
10
  * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
12
11
  *
13
12
  * Usage:
@@ -18,10 +17,14 @@
18
17
  * The module also exports its functions and only runs `main()` when executed directly,
19
18
  * so it can be imported (for testing/reuse) without side effects.
20
19
  */
20
+ /**
21
+ * A rule file. `paths` scopes it: Claude Code loads it only for matching files.
22
+ */
21
23
  type Rule = {
22
24
  file: string;
23
25
  name: string;
24
26
  description?: string;
27
+ paths?: string[];
25
28
  content: string;
26
29
  };
27
30
  type Skill = {
@@ -54,8 +57,8 @@ export declare function packageFiles(rules: Rule[], skills: Skill[]): Map<string
54
57
  export declare function readUserFiles(cwd: string): Map<string, string>;
55
58
  /**
56
59
  * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
57
- * package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
58
- * `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
60
+ * package files into both, pointing straight at the package, and the user's own `.agents` files into `.claude`.
61
+ * Real files and linked directories are the user's - never written over or through. Dead links are
59
62
  * removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
60
63
  * records them (and keeps them out of git, so the user's own files there stay tracked).
61
64
  *
@@ -82,13 +85,12 @@ export declare function checkClaudeMdSafety(claudeMdPath: string): void;
82
85
  */
83
86
  export declare function symlinkClaudeMd(cwd: string): void;
84
87
  /**
85
- * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
86
- * and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
88
+ * Generate AGENTS.md with a `# Rules` section: one entry per rule (the package's and the user's own) with
89
+ * its frontmatter `description`, the `paths` it is scoped to and a plain link to its `.agents/rules` entry.
87
90
  *
88
- * `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
89
- * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
90
- * under `.claude/rules`, symlinks included) - no reference to them is needed here.
91
- * The sections below are for other tools that only read AGENTS.md.
91
+ * The links are plain, never `@path` imports: Claude Code loads `.claude/rules` itself (syncAgentDirs() links them
92
+ * there) and honours each rule's `paths`, while an `@` import would load every rule into every session, scoped or not.
93
+ * Codex, which expands no `@`, reads this index.
92
94
  */
93
95
  export declare function generateAgentsFile(rules: Rule[], customSection: string | null): string;
94
96
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAClF,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC9B,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AA8M1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAmBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBhF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAc9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAkClH;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,CAYpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAsBtF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAmD3B"}
1
+ {"version":3,"file":"lintPrepare.d.ts","sourceRoot":"","sources":["../src/lintPrepare.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;GAiBG;AAUH;;GAEG;AACH,KAAK,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AACpG,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC9B,KAAK,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AA4N1F;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAmBlC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,KAAK,EAAE,CAQpC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBhF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAc9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAkClH;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,CAYpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAc9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAatF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAW9D;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAmD3B"}
@@ -3,11 +3,10 @@
3
3
  * @kirill.konshin/lint
4
4
  *
5
5
  * This script makes `rules`, `commands` and `skills` real directories in the consuming project's
6
- * `.agents` (canonical, cross-tool), `.claude` (Claude Code) and `.codex`, and fills them with
6
+ * `.agents` (canonical, cross-tool) and `.claude` (Claude Code), and fills them with
7
7
  * file symlinks only: package rules and skills (every file a skill folder ships, plus the package
8
- * README.md next to its SKILL.md, so a skill can reference `@README.md`) go into all three, pointing
9
- * straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`
10
- * and `.codex`. It also
8
+ * README.md next to its SKILL.md, so a skill can reference `@README.md`) go into both, pointing
9
+ * straight at the installed package; the user's own files in `.agents` are mirrored into `.claude`. It also
11
10
  * generates an `AGENTS.md` file for other tools, with `CLAUDE.md` symlinked to `AGENTS.md`.
12
11
  *
13
12
  * Usage:
@@ -30,9 +29,9 @@ const RULES_DIR = path.join(__dirname, '../rules');
30
29
  const SKILLS_DIR = path.join(__dirname, '../skills');
31
30
  const README_FILE = path.join(__dirname, '../README.md');
32
31
  // `.agents` is the cross-tool location (Codex, Cursor, Antigravity) holding the package links and the user's own
33
- // files, the latter are mirrored into `.claude` (Claude Code reads nothing else) and `.codex`
32
+ // files, the latter are mirrored into `.claude` (Claude Code reads nothing else)
34
33
  const CANONICAL_AGENT_DIR = '.agents';
35
- const MIRROR_AGENT_DIRS = ['.claude', '.codex'];
34
+ const MIRROR_AGENT_DIRS = ['.claude'];
36
35
  const AGENT_DIRS = [CANONICAL_AGENT_DIR, ...MIRROR_AGENT_DIRS];
37
36
  const AGENT_KINDS = ['rules', 'commands', 'skills'];
38
37
  const GITIGNORE = '.gitignore';
@@ -58,22 +57,34 @@ const toTitle = (name) => {
58
57
  return title.charAt(0).toUpperCase() + title.slice(1);
59
58
  };
60
59
  /**
61
- * The `description` field of a rule's YAML frontmatter.
60
+ * A rule's YAML frontmatter, empty when it has none.
62
61
  */
63
- const readDescription = (content) => {
62
+ const readFrontmatter = (content) => {
64
63
  const frontmatter = FRONTMATTER.exec(content)?.[1];
65
- const description = frontmatter ? parse(frontmatter)?.description : undefined;
66
- return typeof description === 'string' ? description.trim() : undefined;
64
+ const parsed = frontmatter ? parse(frontmatter) : undefined;
65
+ return parsed && typeof parsed === 'object' ? parsed : {};
66
+ };
67
+ /**
68
+ * A frontmatter field read as a list of strings: one string, or a list of them.
69
+ */
70
+ const stringList = (value) => {
71
+ const items = typeof value === 'string' ? [value] : Array.isArray(value) ? value : [];
72
+ const strings = items.filter((item) => typeof item === 'string' && item.trim() !== '');
73
+ return strings.length ? strings : undefined;
67
74
  };
68
75
  /**
69
76
  * `file` is the path inside a rules dir, e.g. `auth.md` or `frontend/react.md`.
70
77
  */
71
- const toRule = (file, content) => ({
72
- file,
73
- name: path.posix.basename(file, '.md'),
74
- description: readDescription(content),
75
- content,
76
- });
78
+ const toRule = (file, content) => {
79
+ const { description, paths } = readFrontmatter(content);
80
+ return {
81
+ file,
82
+ name: path.posix.basename(file, '.md'),
83
+ description: typeof description === 'string' ? description.trim() : undefined,
84
+ paths: stringList(paths),
85
+ content,
86
+ };
87
+ };
77
88
  /**
78
89
  * Real files under `dir`, as paths relative to `root` - symlinks (incl. the package links next to them), linked
79
90
  * directories and dotfiles (`.gitignore`, `.DS_Store`) are skipped.
@@ -271,8 +282,8 @@ export function readUserFiles(cwd) {
271
282
  }
272
283
  /**
273
284
  * Make `rules`, `commands` and `skills` real directories in every agent dir and link the files we know into them:
274
- * package files into all three, pointing straight at the package, the user's own `.agents` files into `.claude` and
275
- * `.codex`. Real files and linked directories are the user's - never written over or through. Dead links are
285
+ * package files into both, pointing straight at the package, and the user's own `.agents` files into `.claude`.
286
+ * Real files and linked directories are the user's - never written over or through. Dead links are
276
287
  * removed, and so are links from the previous run that are no longer placed: each directory's generated `.gitignore`
277
288
  * records them (and keeps them out of git, so the user's own files there stay tracked).
278
289
  *
@@ -354,32 +365,22 @@ export function symlinkClaudeMd(cwd) {
354
365
  fs.symlinkSync(AGENTS_FILE, claudeMdPath);
355
366
  }
356
367
  /**
357
- * Generate AGENTS.md with a `# Rules` section: a `## Title` block per rule file (the package's
358
- * and the user's own) with its frontmatter `description` and a reference to its `.agents/rules` entry.
368
+ * Generate AGENTS.md with a `# Rules` section: one entry per rule (the package's and the user's own) with
369
+ * its frontmatter `description`, the `paths` it is scoped to and a plain link to its `.agents/rules` entry.
359
370
  *
360
- * `.claude/rules/*.md` are symlinked by syncAgentDirs() above and auto-discovered by
361
- * Claude Code at launch (confirmed: Claude Code recursively loads every `.md` file
362
- * under `.claude/rules`, symlinks included) - no reference to them is needed here.
363
- * The sections below are for other tools that only read AGENTS.md.
371
+ * The links are plain, never `@path` imports: Claude Code loads `.claude/rules` itself (syncAgentDirs() links them
372
+ * there) and honours each rule's `paths`, while an `@` import would load every rule into every session, scoped or not.
373
+ * Codex, which expands no `@`, reads this index.
364
374
  */
365
375
  export function generateAgentsFile(rules, customSection) {
366
- /**
367
- * @see https://code.claude.com/docs/en/memory#import-additional-files
368
- * @see https://github.com/anthropics/claude-code/issues/13614 @import -> @path/file.md in Claude
369
- * @see https://github.com/openai/codex/issues/17401 - no @path/file.md in Codex yet
370
- */
371
- const sections = rules.map((rule) => {
376
+ const entries = rules.map((rule) => {
372
377
  // the canonical entry (a package link or the user's own file), not the package install path
373
378
  const rulePath = `${CANONICAL_AGENT_DIR}/rules/${rule.file}`;
374
- return [
375
- `## ${toTitle(rule.name)}`,
376
- rule.description,
377
- `See instructions in @${rulePath} [${rulePath}](${rulePath}).`,
378
- ]
379
- .filter(Boolean)
380
- .join('\n\n');
379
+ const description = rule.description ? ` — ${rule.description}` : '';
380
+ const scope = rule.paths ? `; when touching ${rule.paths.map((glob) => `\`${glob}\``).join(', ')}` : '';
381
+ return `- **${toTitle(rule.name)}**${description}${scope}: [${rulePath}](${rulePath})`;
381
382
  });
382
- const generated = `${HEADER}\n\n# Rules\n\n${sections.join('\n\n')}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
383
+ const generated = `${HEADER}\n\n# Rules\n\n${entries.join('\n')}\n\n${FOOTER}\n\n${GENERATED_MARKER}`;
383
384
  return customSection ? `${generated}\n\n${customSection}\n` : `${generated}\n`;
384
385
  }
385
386
  /**
@@ -0,0 +1,23 @@
1
+ import type { Linter } from 'eslint';
2
+ /**
3
+ * One structural restriction: a core `no-restricted-*` rule applied under a concern of its own, with the files it
4
+ * governs. Every other field is a flat-config entry field (`files`, `ignores`, ...).
5
+ */
6
+ export type Restriction = Omit<Linter.Config, 'name' | 'plugins' | 'rules'> & {
7
+ /** The concern, registered as `restrict/<name>`; entries of one concern share it. */
8
+ name: string;
9
+ /** Tells apart the entries of one concern. */
10
+ label?: string;
11
+ /** The core rule the concern copies, e.g. `no-restricted-imports`. */
12
+ rule: string;
13
+ /** The rule's options. */
14
+ options: unknown[];
15
+ };
16
+ /**
17
+ * The lint layer: structural rules a syntax or import check decides. Each concern is restricted through its own copy
18
+ * of a core `no-restricted-*` rule, named `restrict/<name>`, because a later flat-config entry replaces an earlier
19
+ * one's options for the same rule — two concerns sharing one core rule would silently drop each other wherever their
20
+ * files overlap. Entries of one concern share its name and differ by `label`.
21
+ */
22
+ export declare function restrictions(entries: Restriction[]): Linter.Config[];
23
+ //# sourceMappingURL=restrictions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"restrictions.d.ts","sourceRoot":"","sources":["../src/restrictions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGrC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,GAAG;IAC1E,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,OAAO,EAAE,OAAO,EAAE,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,CAgBpE"}
@@ -0,0 +1,24 @@
1
+ import { builtinRules } from 'eslint/use-at-your-own-risk';
2
+ /**
3
+ * The lint layer: structural rules a syntax or import check decides. Each concern is restricted through its own copy
4
+ * of a core `no-restricted-*` rule, named `restrict/<name>`, because a later flat-config entry replaces an earlier
5
+ * one's options for the same rule — two concerns sharing one core rule would silently drop each other wherever their
6
+ * files overlap. Entries of one concern share its name and differ by `label`.
7
+ */
8
+ export function restrictions(entries) {
9
+ return [
10
+ {
11
+ name: 'Lint layer',
12
+ plugins: {
13
+ restrict: {
14
+ rules: Object.fromEntries(entries.map(({ name, rule }) => [name, builtinRules.get(rule)])),
15
+ },
16
+ },
17
+ },
18
+ ...entries.map(({ name, label, rule: _rule, options, ...entry }) => ({
19
+ name: `Lint layer: ${label ? `${name} (${label})` : name}`,
20
+ ...entry,
21
+ rules: { [`restrict/${name}`]: ['error', ...options] },
22
+ })),
23
+ ];
24
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kirill.konshin/lint",
3
3
  "description": "ESLint + Prettier + lint-staged config and AI agent rules/skills for monorepos",
4
- "version": "0.5.4",
4
+ "version": "0.5.5",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
package/rules/agent.md CHANGED
@@ -68,7 +68,7 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
68
68
 
69
69
  # `.agents/rules`
70
70
 
71
- - `.agents/rules` must be accompanied by symlinks in `.claude/rules` and `.codex/rules`
71
+ - `.agents/rules` must be accompanied by symlinks in `.claude/rules`
72
72
  - Files should be scoped to certain paths
73
73
  - Files should be small,
74
74
  - Examples not allowed in general
@@ -81,7 +81,7 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
81
81
 
82
82
  # `.agents/skills`
83
83
 
84
- - `.agents/skills` must be accompanied by symlinks in `.claude/skills` and `.codex/skills`
84
+ - `.agents/skills` must be accompanied by symlinks in `.claude/skills`
85
85
  - May define either
86
86
  - A workflow
87
87
  - A process
@@ -94,7 +94,7 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
94
94
 
95
95
  # `.agents/commands`
96
96
 
97
- - `.agents/commands` must be accompanied by symlinks in `.claude/commands` and `.codex/commands`
97
+ - `.agents/commands` must be accompanied by symlinks in `.claude/commands`
98
98
  - Smaller and simpler than skills
99
99
  - One-off commands, not flows
100
100
 
@@ -104,7 +104,7 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
104
104
  - User facing or externally observable behavior
105
105
  - Durable component/system/API contracts & invariants
106
106
  - Not general coding instructions
107
- - Openspec-specific instructions must assume that flow WAS ENTERED, thus `AGENTS.md` or `[.agents|.claude|.codex]/skills` must be used to define how to enter the flow, and how flow should look like from outside perspective (without details)
107
+ - Openspec-specific instructions must assume that flow WAS ENTERED, thus `AGENTS.md` or `[.agents|.claude]/skills` must be used to define how to enter the flow, and how flow should look like from outside perspective (without details)
108
108
  - `openspec/config.yml#context` - should only have very narrow instructions for OpenSpec specifically, when user entered flow
109
109
  - Context will already contain root `AGENTS.md`, no duplication needed
110
110
  - `openspec/config.yml#rules.[specs|proposal]` - very narrow sets of rules specifically for defined part of the flow when it's entered
@@ -115,6 +115,7 @@ Prefer one authoritative location for each concern. Reference it elsewhere inste
115
115
  - Requirements and scenarios should (preferrably) be proven by tests, and may be cited in tests for stronger connection
116
116
  - Tests should be validated that they do what spec says (optional, unless project mandates this in root `AGENTS.md`)
117
117
  - Code citations must resolve, not checked for validity
118
+ - Comments, descriptions, prompt or documentation text, and citations are not evidence that code complies, and their absence or wording is never a violation
118
119
 
119
120
  # Common for `AGENTS.md` `.agents/rules` `.agents/skills`
120
121
 
@@ -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 or inside the block of the scenario it qualifies.
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. Inside a scenario's block, the line exempts that scenario. Coverage lists every gap with its tracker. |
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 that carries a tracker. `scenario` is the slug of the scenario whose block holds the line, or `null` for a line under the requirement; `exempts` lists the slugs of the scenarios it exempts, empty when it exempts none.
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. Under the requirement, it names by title the scenarios it exempts; inside a scenario's block, it exempts that scenario. A gap is never restated as a scenario, and a scenario that a gap conditions states that condition.
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`, `.codex/rules`) | Hard constraints, loaded when the agent touches `openspec/**`. | `lint-prepare` (`@kirill.konshin/lint`) |
8
- | Skill `.agents/skills/spec-steward` (+ `.claude/skills`, `.codex/skills`) | The procedures, the model, the contract and the scripts. | `lint-prepare` |
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 text. Reports identical, drifted and one-sided rules; choosing the wording stays with the owner.
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
- /** Body without heading, normalized. @param {Requirement} r */
15
- const body = (r) => normalize(r.block.split('\n').slice(1).join('\n'));
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.block), words(x.block)) }))
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 = body(ra) === body(rb) && ra.name === rb.name;
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.block, rb.block)),
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.some((s) => s !== g.scenario))
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 or whose block it sits in).
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, scenario: string | null, exempts: string[],
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
- scenario: m.scenario,
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
- : requirementGaps.length
70
- ? `known gap (${requirementGaps.map((g) => mdx(g.tracker)).join(', ')})`
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';
@@ -165,7 +165,6 @@ export function evidenceModel(corpus, citations, sources) {
165
165
  tracker: g.tracker,
166
166
  text: g.text,
167
167
  line: g.line,
168
- scenario: g.scenario,
169
168
  exempts: g.exempts,
170
169
  })),
171
170
  scenarios: r.scenarios.map((s) => ({