@agent-ix/quoin 0.4.0 → 0.4.1

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
@@ -105,14 +105,6 @@ The default module set defines the spec archetypes and domain-object vocabulary.
105
105
  - **`spec-risk-complexity-analysis`** — technical risk and volatility before tasking
106
106
  - **`spec-security-analysis`** — applicable security standards and compliance traceability
107
107
 
108
- ### Agent Workflows
109
-
110
- Multi-agent workflows that fan out, run lenses in parallel, and synthesize results:
111
-
112
- - **`review`** — parallel review lenses → dedupe → sync
113
- - **`matrix`** — coverage analysis and Test Matrix construction
114
- - **`to-plan`** — requirements → dependency-aware TDD plan
115
-
116
108
  ## Install
117
109
 
118
110
  Installing quoin into Claude is **two steps**: the CLI (from public npm) and the plugin
@@ -10,73 +10,73 @@ schemaVersion: 1
10
10
  name: quoin-default-modules
11
11
  entries:
12
12
  - name: spec-artifacts-iso
13
- version: "0.4.0"
13
+ version: "0.5.0"
14
14
  defaultEnabled: true
15
15
  source:
16
16
  type: git-subdir
17
17
  url: agent-ix/spec-artifacts-iso
18
18
  path: spec_artifacts_iso
19
- ref: v0.4.0
19
+ ref: v0.5.0
20
20
 
21
21
  - name: spec-artifacts-app
22
- version: "0.2.0"
22
+ version: "0.3.0"
23
23
  defaultEnabled: true
24
24
  source:
25
25
  type: git-subdir
26
26
  url: agent-ix/spec-artifacts-app
27
27
  path: spec_artifacts_app
28
- ref: v0.2.0
28
+ ref: v0.3.0
29
29
 
30
30
  - name: spec-artifacts-process
31
- version: "0.4.0"
31
+ version: "0.5.0"
32
32
  defaultEnabled: true
33
33
  source:
34
34
  type: git-subdir
35
35
  url: agent-ix/spec-artifacts-process
36
36
  path: spec_artifacts_process
37
- ref: v0.4.0
37
+ ref: v0.5.0
38
38
 
39
39
  - name: spec-objects-business
40
- version: "0.3.0"
40
+ version: "0.4.0"
41
41
  defaultEnabled: true
42
42
  source:
43
43
  type: git-subdir
44
44
  url: agent-ix/spec-objects-business
45
45
  path: spec_objects_business
46
- ref: v0.3.0
46
+ ref: v0.4.0
47
47
 
48
48
  - name: spec-objects-architecture
49
- version: "0.3.0"
49
+ version: "0.4.0"
50
50
  defaultEnabled: true
51
51
  source:
52
52
  type: git-subdir
53
53
  url: agent-ix/spec-objects-architecture
54
54
  path: spec_objects_architecture
55
- ref: v0.3.0
55
+ ref: v0.4.0
56
56
 
57
57
  - name: spec-objects-enterprise
58
- version: "0.2.0"
58
+ version: "0.3.0"
59
59
  defaultEnabled: true
60
60
  source:
61
61
  type: git-subdir
62
62
  url: agent-ix/spec-objects-enterprise
63
63
  path: spec_objects_enterprise
64
- ref: v0.2.0
64
+ ref: v0.3.0
65
65
 
66
66
  - name: spec-objects-operational
67
- version: "0.3.0"
67
+ version: "0.4.0"
68
68
  defaultEnabled: true
69
69
  source:
70
70
  type: git-subdir
71
71
  url: agent-ix/spec-objects-operational
72
72
  path: spec_objects_operational
73
- ref: v0.3.0
73
+ ref: v0.4.0
74
74
 
75
75
  - name: spec-objects-security
76
- version: "0.2.0"
76
+ version: "0.3.0"
77
77
  defaultEnabled: true
78
78
  source:
79
79
  type: git-subdir
80
80
  url: agent-ix/spec-objects-security
81
81
  path: spec_objects_security
82
- ref: v0.2.0
82
+ ref: v0.3.0
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agent-ix/quoin",
3
3
  "description": "Spec-driven development for Claude Code — author validated, ISO/IEC/IEEE 29148-aligned specs, then plan and build against them.",
4
- "version": "0.4.0",
4
+ "version": "0.4.1",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: spec-ears-analysis
3
+ description: Analyze requirement statements (FR/NFR/StR) for EARS requirement-grammar conformance and author a SpecReview of the findings.
4
+ ---
5
+
6
+ # EARS Requirement-Grammar Analysis
7
+
8
+ This skill analyzes the natural-language **requirement statements** in a spec
9
+ (FR Description/Behavior/Constraints, NFR Statement, StR Stakeholder Need)
10
+ against **EARS** (Easy Approach to Requirements Syntax), and authors one
11
+ `SpecReview` document recording the findings.
12
+
13
+ It pairs the **deterministic engine check** (quire-rs FR-042, the `iso-spec-core`
14
+ grammar) with the **semantic judgment the engine cannot make** — together they
15
+ form the lens.
16
+
17
+ ## Process
18
+
19
+ 1. **Run the engine check.** From the repo root:
20
+
21
+ ```bash
22
+ quire validate --scope . "spec/**/*.md" --summary
23
+ ```
24
+
25
+ Read the `[ears:<check>]` warnings and the `GrammarSummary` line. The engine
26
+ flags, per statement:
27
+ - `non-singular` — more than one `shall` (can't map cleanly to one AC).
28
+ - `vague-response` — `support`/`handle`/`manage`/`process`/`provide`/
29
+ `enable`/`be able to` (unverifiable).
30
+ - `missing-subject` — no named system/actor before `shall`.
31
+ - `non-canonical-trigger` — `On …`/`Upon`/`After`/`During` instead of
32
+ `When …`/`While …`.
33
+ - `unclassifiable` — has `shall` but matches no EARS pattern.
34
+
35
+ These are advisory (they never fail `quire validate`); this lens records
36
+ them as review findings.
37
+
38
+ 2. **Add the semantic judgment** (what the engine cannot check deterministically):
39
+ - **Keyword-vs-intent** — does a `When …` statement describe a momentary
40
+ *event*, or is it really a continuous `While …` *state* (or vice-versa)?
41
+ - **Genuinely concrete response** — a statement can pass the vague-verb
42
+ lexicon yet still be unmeasurable ("shall be fast", "shall be robust").
43
+ - **Right pattern for the obligation** — an unwanted condition stated as
44
+ `When …` instead of `If … then …`.
45
+
46
+ 3. **Author the SpecReview.** Fetch the template once:
47
+
48
+ ```bash
49
+ quoin write --types SpecReview
50
+ ```
51
+
52
+ Write one document to `spec/reviews/ears-conformance.md` with
53
+ `analysis: ears-conformance` in the frontmatter, a `## Summary` (one or two
54
+ sentences: how many statements, how many clean, the dominant defect), and a
55
+ validated `## Findings` table:
56
+
57
+ | ID | Severity | Summary | Refs |
58
+ | --- | --- | --- | --- |
59
+ | FND-001 | medium | FR-001 Description packs two `shall` into one statement — split into atomic requirements | FR-001 |
60
+ | FND-002 | low | FR-003 leads with `On startup, …`; use `When the service starts, …` | FR-003 |
61
+
62
+ - `Severity` ∈ `low`/`medium`/`high`. Suggested mapping: `non-singular`
63
+ and `missing-subject` → **medium** (they degrade traceability);
64
+ `vague-response`/`unclassifiable` → **medium** when the response is truly
65
+ unverifiable, else **low**; `non-canonical-trigger` → **low** (cosmetic).
66
+ Raise to **high** any statement whose ambiguity changes what gets built.
67
+ - `Refs` names the offending FR/NFR/StR id.
68
+ - Combine the engine findings with your step-2 semantic findings into one
69
+ table; attribute each row to its statement.
70
+
71
+ 4. **Validate + record.**
72
+
73
+ ```bash
74
+ quire validate --scope . "spec/reviews/ears-conformance.md"
75
+ ```
76
+
77
+ Fix any structural errors in the review doc. The doc syncs into filament-core
78
+ as a `SpecReview` artifact like every other analysis lens.
79
+
80
+ ## Notes
81
+
82
+ - Scope is **requirement-bearing** artifacts only: FR, NFR, StR. US stories
83
+ (`As a / I want / So that`) and tests are out of scope.
84
+ - This lens is advisory by default. To make EARS a **gate** for a converted
85
+ repo, run `quire validate --strict` in that repo's CI — `--strict` escalates
86
+ the EARS warnings to a failing exit.
87
+ - Per-archetype dialects the engine already applies (don't re-flag them): an
88
+ enumerated `The X SHALL:` + numbered list is one statement; StR may use a
89
+ stakeholder subject; an NFR with no trigger is fine.
@@ -16,6 +16,29 @@ Use this skill to create the requirements Test Matrix and ensure comprehensive c
16
16
  5. State Transition: Test all valid state transitions (if applicable).
17
17
  6. Edge Case: Identify and test extreme/unusual scenarios.
18
18
 
19
+ ## EARS precondition (atomic, mappable requirements)
20
+
21
+ Coverage (Rule 1) is only meaningful when each requirement states **one**
22
+ obligation — a statement packing two `shall` clauses cannot map cleanly to one
23
+ Acceptance Criterion, so its matrix row is ambiguous. Before building the
24
+ matrix, run the EARS requirement-grammar check:
25
+
26
+ ```bash
27
+ quire validate --scope . "spec/**/*.md" --summary
28
+ ```
29
+
30
+ Treat these `[ears:…]` findings as **un-mappable requirements to fix first**,
31
+ not coverage you can claim:
32
+
33
+ - `non-singular` — split the statement into one requirement per `shall`, then
34
+ map each to its own AC/TC.
35
+ - `unclassifiable` / `missing-subject` — the obligation is unclear; clarify the
36
+ requirement before authoring a TC against it.
37
+
38
+ Do not mark the matrix ✅ Complete while non-singular or unclassifiable
39
+ requirements remain — the coverage they appear to have is illusory. (The check
40
+ is advisory; this skill treats it as a quality gate for the matrix.)
41
+
19
42
  ## Process
20
43
 
21
44
  1. Initialize:
@@ -17,10 +17,10 @@ Before reviewing, present these options to the user and let them choose:
17
17
 
18
18
  - **base** — the **Checklist** only: ID formats, US/FR/TC quality, and the six coverage
19
19
  rules. No analysis skills.
20
- - **all** — `base` plus all six analyses below.
21
- - **subset** — `base` plus the analyses the user picks from the six below.
20
+ - **all** — `base` plus all seven analyses below.
21
+ - **subset** — `base` plus the analyses the user picks from the seven below.
22
22
 
23
- The six analyses:
23
+ The seven analyses:
24
24
 
25
25
  | Analysis | Skill |
26
26
  | --- | --- |
@@ -30,6 +30,7 @@ The six analyses:
30
30
  | evidence | `spec-evidence-analysis` |
31
31
  | risk-complexity | `spec-risk-complexity-analysis` |
32
32
  | scope-boundary | `spec-scope-boundary-analysis` |
33
+ | ears-conformance | `spec-ears-analysis` |
33
34
 
34
35
  ## Process
35
36