@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 +9 -4
- 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 +14 -12
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +39 -38
- 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/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
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)
|
|
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
|
|
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)
|
|
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
|
|
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,
|
|
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"}
|
package/dist/configs/testing.js
CHANGED
|
@@ -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>;
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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
|
/**
|
package/dist/lintPrepare.d.ts
CHANGED
|
@@ -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)
|
|
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
|
|
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
|
|
58
|
-
*
|
|
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:
|
|
86
|
-
*
|
|
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
|
|
89
|
-
*
|
|
90
|
-
*
|
|
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
|
|
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"}
|
package/dist/lintPrepare.js
CHANGED
|
@@ -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)
|
|
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
|
|
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)
|
|
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'
|
|
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
|
-
*
|
|
60
|
+
* A rule's YAML frontmatter, empty when it has none.
|
|
62
61
|
*/
|
|
63
|
-
const
|
|
62
|
+
const readFrontmatter = (content) => {
|
|
64
63
|
const frontmatter = FRONTMATTER.exec(content)?.[1];
|
|
65
|
-
const
|
|
66
|
-
return typeof
|
|
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
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
|
275
|
-
*
|
|
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:
|
|
358
|
-
*
|
|
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
|
|
361
|
-
*
|
|
362
|
-
*
|
|
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
|
-
|
|
375
|
-
|
|
376
|
-
|
|
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${
|
|
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
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`
|
|
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`
|
|
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`
|
|
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
|
|
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
|
|
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';
|