@agent-ix/quoin 0.1.3
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/.agents/plugins/marketplace.json +14 -0
- package/.claude-plugin/marketplace.json +16 -0
- package/.claude-plugin/plugin.json +8 -0
- package/.codex-plugin/plugin.json +27 -0
- package/.github/plugin/marketplace.json +16 -0
- package/LICENSE +21 -0
- package/README.md +266 -0
- package/bin/quoin.js +14 -0
- package/default-modules.yaml +82 -0
- package/dist/base-DrUMkAh1.js +137 -0
- package/dist/base.d.ts +23 -0
- package/dist/base.d.ts.map +1 -0
- package/dist/catalog.d.ts +32 -0
- package/dist/catalog.d.ts.map +1 -0
- package/dist/cli.d.ts +18 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +20 -0
- package/dist/commands/catalog/index.d.ts +2 -0
- package/dist/commands/catalog/index.d.ts.map +1 -0
- package/dist/commands/catalog/index.js +2 -0
- package/dist/commands/catalog/list.d.ts +11 -0
- package/dist/commands/catalog/list.d.ts.map +1 -0
- package/dist/commands/catalog/list.js +22 -0
- package/dist/commands/catalog/show.d.ts +13 -0
- package/dist/commands/catalog/show.d.ts.map +1 -0
- package/dist/commands/catalog/show.js +25 -0
- package/dist/commands/catalog/validate.d.ts +10 -0
- package/dist/commands/catalog/validate.d.ts.map +1 -0
- package/dist/commands/catalog/validate.js +27 -0
- package/dist/commands/config/doctor.d.ts +7 -0
- package/dist/commands/config/doctor.d.ts.map +1 -0
- package/dist/commands/config/doctor.js +15 -0
- package/dist/commands/config/edit.d.ts +7 -0
- package/dist/commands/config/edit.d.ts.map +1 -0
- package/dist/commands/config/edit.js +13 -0
- package/dist/commands/config/get.d.ts +11 -0
- package/dist/commands/config/get.d.ts.map +1 -0
- package/dist/commands/config/get.js +20 -0
- package/dist/commands/config/index.d.ts +2 -0
- package/dist/commands/config/index.d.ts.map +1 -0
- package/dist/commands/config/index.js +2 -0
- package/dist/commands/config/set.d.ts +12 -0
- package/dist/commands/config/set.d.ts.map +1 -0
- package/dist/commands/config/set.js +26 -0
- package/dist/commands/matrix.d.ts +14 -0
- package/dist/commands/matrix.d.ts.map +1 -0
- package/dist/commands/matrix.js +15 -0
- package/dist/commands/module/ensure-defaults.d.ts +8 -0
- package/dist/commands/module/ensure-defaults.d.ts.map +1 -0
- package/dist/commands/module/ensure-defaults.js +17 -0
- package/dist/commands/module/index.d.ts +2 -0
- package/dist/commands/module/index.d.ts.map +1 -0
- package/dist/commands/module/index.js +2 -0
- package/dist/commands/module/install.d.ts +11 -0
- package/dist/commands/module/install.d.ts.map +1 -0
- package/dist/commands/module/install.js +22 -0
- package/dist/commands/module/list.d.ts +8 -0
- package/dist/commands/module/list.d.ts.map +1 -0
- package/dist/commands/module/list.js +13 -0
- package/dist/commands/module/remove.d.ts +10 -0
- package/dist/commands/module/remove.d.ts.map +1 -0
- package/dist/commands/module/remove.js +16 -0
- package/dist/commands/plugin/deprecation.d.ts +10 -0
- package/dist/commands/plugin/deprecation.d.ts.map +1 -0
- package/dist/commands/plugin/ensure-defaults.d.ts +8 -0
- package/dist/commands/plugin/ensure-defaults.d.ts.map +1 -0
- package/dist/commands/plugin/ensure-defaults.js +12 -0
- package/dist/commands/plugin/index.d.ts +2 -0
- package/dist/commands/plugin/index.d.ts.map +1 -0
- package/dist/commands/plugin/index.js +2 -0
- package/dist/commands/plugin/install.d.ts +8 -0
- package/dist/commands/plugin/install.d.ts.map +1 -0
- package/dist/commands/plugin/install.js +12 -0
- package/dist/commands/plugin/list.d.ts +8 -0
- package/dist/commands/plugin/list.d.ts.map +1 -0
- package/dist/commands/plugin/list.js +12 -0
- package/dist/commands/plugin/remove.d.ts +8 -0
- package/dist/commands/plugin/remove.d.ts.map +1 -0
- package/dist/commands/plugin/remove.js +12 -0
- package/dist/commands/review.d.ts +14 -0
- package/dist/commands/review.d.ts.map +1 -0
- package/dist/commands/review.js +15 -0
- package/dist/commands/to-plan.d.ts +14 -0
- package/dist/commands/to-plan.d.ts.map +1 -0
- package/dist/commands/to-plan.js +15 -0
- package/dist/commands/update.d.ts +13 -0
- package/dist/commands/update.d.ts.map +1 -0
- package/dist/commands/update.js +34 -0
- package/dist/commands/write.d.ts +16 -0
- package/dist/commands/write.d.ts.map +1 -0
- package/dist/commands/write.js +33 -0
- package/dist/config-schema-Dp-vlxuR.js +13 -0
- package/dist/config-schema.d.ts +52 -0
- package/dist/config-schema.d.ts.map +1 -0
- package/dist/deprecation-fRxUHoxv.js +4 -0
- package/dist/flow-command-SMjCSOFg.js +88 -0
- package/dist/flow-command.d.ts +25 -0
- package/dist/flow-command.d.ts.map +1 -0
- package/dist/flows.d.ts +7 -0
- package/dist/flows.d.ts.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +9 -0
- package/dist/modules-CW8pBK41.js +22 -0
- package/dist/modules.d.ts +10 -0
- package/dist/modules.d.ts.map +1 -0
- package/dist/org.d.ts +61 -0
- package/dist/org.d.ts.map +1 -0
- package/dist/plugins-GSxafyD3.js +77 -0
- package/dist/plugins.d.ts +13 -0
- package/dist/plugins.d.ts.map +1 -0
- package/dist/version-_1nY4KyJ.js +17 -0
- package/dist/version.d.ts +3 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/write-CQAitcI5.js +156 -0
- package/dist/write.d.ts +28 -0
- package/dist/write.d.ts.map +1 -0
- package/package.json +119 -0
- package/skills/gap-analysis/SKILL.md +97 -0
- package/skills/gap-analysis/references/step-1-target-selection.md +53 -0
- package/skills/gap-analysis/references/step-2-plan-completion.md +49 -0
- package/skills/gap-analysis/references/step-3-matrix-verification.md +54 -0
- package/skills/gap-analysis/references/step-4-underspecified-code.md +63 -0
- package/skills/gap-analysis/references/step-5-semantic-review.md +51 -0
- package/skills/gap-analysis/references/step-6-specreview-artifact.md +95 -0
- package/skills/spec-app-review/SKILL.md +51 -0
- package/skills/spec-app-review/references/checklist.md +197 -0
- package/skills/spec-dependency-analysis/SKILL.md +75 -0
- package/skills/spec-ears-analysis/SKILL.md +89 -0
- package/skills/spec-evidence-analysis/SKILL.md +78 -0
- package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
- package/skills/spec-ideation/SKILL.md +46 -0
- package/skills/spec-integrity-analysis/SKILL.md +47 -0
- package/skills/spec-matrix/SKILL.md +168 -0
- package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
- package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
- package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
- package/skills/spec-matrix/assets/test-matrix-example.md +104 -0
- package/skills/spec-matrix/assets/test-matrix-template.md +123 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
- package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
- package/skills/spec-object-review/SKILL.md +125 -0
- package/skills/spec-object-review/references/object-type-guide.md +118 -0
- package/skills/spec-review/SKILL.md +71 -0
- package/skills/spec-review/references/checklist.md +50 -0
- package/skills/spec-review/workflow-assets/skills/review/SKILL.md +96 -0
- package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +60 -0
- package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +68 -0
- package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
- package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
- package/skills/spec-security-analysis/SKILL.md +84 -0
- package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
- package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
- package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
- package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
- package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
- package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
- package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
- package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
- package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
- package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
- package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
- package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
- package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
- package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
- package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
- package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
- package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
- package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
- package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
- package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
- package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
- package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
- package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
- package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
- package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
- package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
- package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
- package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
- package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
- package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
- package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
- package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
- package/skills/spec-security-analysis/references/soc2/index.md +46 -0
- package/skills/spec-security-analysis/references/standards-index.md +46 -0
- package/skills/spec-to-plan/SKILL.md +75 -0
- package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
- package/skills/spec-to-plan/references/step-1-analysis.md +88 -0
- package/skills/spec-to-plan/references/step-2-test-plan.md +43 -0
- package/skills/spec-to-plan/references/step-3-execution-plan.md +218 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +44 -0
- package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +85 -0
- package/skills/specify/SKILL.md +154 -0
- package/skills/specify/assets/app-spec-template.md +143 -0
- package/skills/specify/assets/spec-template.md +299 -0
- package/skills/specify/references/integration-tests.md +72 -0
- package/skills/specify/references/us-to-fr.md +40 -0
- package/skills/specify/references/writing-good-requirements.md +61 -0
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Step 4: Underspecified Code (reverse gap)
|
|
2
|
+
|
|
3
|
+
**Goal**: Find the *reverse* gap — code and behavior that exist with **no owning
|
|
4
|
+
requirement**, plus stubs that masquerade as complete. Steps 2–3 verify spec→code/test
|
|
5
|
+
coverage; this step verifies code→spec, catching scope that was implemented but never
|
|
6
|
+
specified.
|
|
7
|
+
|
|
8
|
+
Reuse the detection heuristics in
|
|
9
|
+
`~/dev/agent_skills/implementation-gap-analysis/SKILL.md` — don't reinvent them.
|
|
10
|
+
|
|
11
|
+
## A. Untraced behavior (code with no requirement)
|
|
12
|
+
|
|
13
|
+
1. **Inventory the surface.** List the component's real behaviors — public
|
|
14
|
+
functions/methods, CLI commands/flags, HTTP endpoints, events, config knobs.
|
|
15
|
+
2. **Trace each to a requirement.** A behavior is *traced* if it maps to an StR/US/FR/NFR
|
|
16
|
+
(via the matrix `Traces To`, a requirement that describes it, or a Task `references`
|
|
17
|
+
edge that owns it).
|
|
18
|
+
3. **Flag the untraced.** Behavior with no owning requirement → finding:
|
|
19
|
+
- `high` if it is user-visible or security/data-affecting (an endpoint, a CLI command, a
|
|
20
|
+
destructive operation) — unspecified surface area.
|
|
21
|
+
- `medium` for internal-but-meaningful logic with no requirement.
|
|
22
|
+
- `low` for trivial helpers/glue.
|
|
23
|
+
`Refs` = the code location (`path::symbol`).
|
|
24
|
+
|
|
25
|
+
## B. Implied requirements from code patterns
|
|
26
|
+
|
|
27
|
+
Map suspicious patterns to the requirement that *should* exist (per the
|
|
28
|
+
implementation-gap-analysis table):
|
|
29
|
+
|
|
30
|
+
| Code pattern | Missing requirement type |
|
|
31
|
+
| --- | --- |
|
|
32
|
+
| Defensive code (try/catch, null guards) | Robustness (NFR) |
|
|
33
|
+
| Ambiguous identity/equality logic | Integrity (StR) |
|
|
34
|
+
| Side effects / IO in core logic | Determinism (StR) |
|
|
35
|
+
| Recursion / unbounded structures | Topology / limits (NFR) |
|
|
36
|
+
| Unmapped constraints | Traceability (FR/StR/NFR) |
|
|
37
|
+
|
|
38
|
+
Each unstated-but-implemented constraint → `medium` finding.
|
|
39
|
+
|
|
40
|
+
## C. Stubs masquerading as complete
|
|
41
|
+
|
|
42
|
+
Scan **source** (not just tests) for hollow implementations the plan/matrix may report as
|
|
43
|
+
done:
|
|
44
|
+
|
|
45
|
+
| Stub | Detect | Severity |
|
|
46
|
+
| --- | --- | --- |
|
|
47
|
+
| Tiny file (≤5 lines, excl. `__init__`) | line count | high |
|
|
48
|
+
| `pass` / placeholder return (`{}`,`[]`,`None`,`"not implemented"`) body | grep/AST | high |
|
|
49
|
+
| Protocol/ABC-only with no concrete impl | structure | high |
|
|
50
|
+
| Re-export-only module | structure | medium (may be intentional) |
|
|
51
|
+
| Trivially-covered stub (≤5 lines @ 100% cov) | coverage + size | medium |
|
|
52
|
+
|
|
53
|
+
A stub behind a `done` task or a ✅ matrix row is a `high` finding (false completion).
|
|
54
|
+
|
|
55
|
+
## Output of this step
|
|
56
|
+
|
|
57
|
+
Findings for untraced behavior, implied-but-missing requirements, and stubs, each with
|
|
58
|
+
`Refs` = code location, plus a count of untraced behaviors/stubs for `## Coverage`.
|
|
59
|
+
|
|
60
|
+
## Notes
|
|
61
|
+
|
|
62
|
+
- This is the bridge to better specs: untraced behavior usually means a requirement should
|
|
63
|
+
be authored (`/specify`) — but gap-analysis only **reports** it; it does not author specs.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Step 5: Semantic Review (OPTIONAL)
|
|
2
|
+
|
|
3
|
+
**Goal**: Go beyond presence and traceability to *meaning* — for each requirement↔test↔code
|
|
4
|
+
triple, judge whether they actually agree. This is the expensive, judgment-heavy pass.
|
|
5
|
+
|
|
6
|
+
## Gate first
|
|
7
|
+
|
|
8
|
+
**Do not run this step unless the user opts in.** Ask explicitly:
|
|
9
|
+
|
|
10
|
+
> Run the optional semantic review (intent↔test↔code)? It's slower but verifies tests truly
|
|
11
|
+
> validate requirement intent and exercise real code, and that code matches intent.
|
|
12
|
+
|
|
13
|
+
If declined, skip and note "semantic review: skipped" in the SpecReview `## Coverage`.
|
|
14
|
+
|
|
15
|
+
## What to judge (per requirement)
|
|
16
|
+
|
|
17
|
+
For each requirement (FR/US/StR) in scope, with its tagged test(s) (from Step 3) and the
|
|
18
|
+
code it governs (from Step 4), assess three axes:
|
|
19
|
+
|
|
20
|
+
1. **(a) Test validates intent** — does the test actually check the *behavior the
|
|
21
|
+
requirement describes*, including its acceptance criteria, or only an incidental/trivial
|
|
22
|
+
aspect? A test tagged `FR-007-AC-1` that asserts something unrelated to AC-1 fails here.
|
|
23
|
+
2. **(b) Test exercises the code** — does the test run the real implementation, or is it
|
|
24
|
+
hollow? Reuse the implementation-gap-analysis **test-stub / coverage-inflation**
|
|
25
|
+
heuristics: no assertions, weak-only assertions (`is not None`, `isinstance`),
|
|
26
|
+
mock-everything (no real code path), import-only, circular-mock-of-a-stub.
|
|
27
|
+
3. **(c) Code matches intent** — does the implementation actually do what the requirement
|
|
28
|
+
says (semantics, edge cases, error behavior), or has it drifted?
|
|
29
|
+
|
|
30
|
+
Each failing axis → a finding:
|
|
31
|
+
- `high` — test does not validate intent **or** does not exercise code (false confidence),
|
|
32
|
+
or code contradicts the requirement.
|
|
33
|
+
- `medium` — partial validation, meaningful edge cases unchecked, minor drift.
|
|
34
|
+
|
|
35
|
+
`Refs` = `FR-xxx` + test path + `path::symbol`.
|
|
36
|
+
|
|
37
|
+
## How to run it (thoroughness)
|
|
38
|
+
|
|
39
|
+
Fan out for breadth and independence — **one subagent per FR (or per cohesive area)**, each
|
|
40
|
+
returning a structured verdict per axis. Then aggregate the findings. This keeps each
|
|
41
|
+
judgment focused and lets many run concurrently. For a small scope, a single pass is fine.
|
|
42
|
+
|
|
43
|
+
## Output of this step
|
|
44
|
+
|
|
45
|
+
Per-requirement semantic findings (axis a/b/c failures) with `Refs`, plus a note for
|
|
46
|
+
`## Coverage` that semantic review ran and over how many requirements.
|
|
47
|
+
|
|
48
|
+
## Notes
|
|
49
|
+
|
|
50
|
+
- Keep verdicts evidence-based: quote the requirement clause, the assertion, and the code
|
|
51
|
+
line that justify the finding. Avoid speculative "looks wrong" calls.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Step 6: SpecReview Artifact
|
|
2
|
+
|
|
3
|
+
**Goal**: Emit the findings from Steps 1–5 as a single **quire-validated `SpecReview`**
|
|
4
|
+
document with a Verdict, at `reviews/YY-MM-DD-<slug>.md`.
|
|
5
|
+
|
|
6
|
+
## Fetch the template, then author (guardrail)
|
|
7
|
+
|
|
8
|
+
The `SpecReview` archetype lives in `spec-artifacts-process`. Fetch its skeleton first, then
|
|
9
|
+
author, then validate (the ecosystem direct-render-then-validate model):
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
quoin write --types SpecReview
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
If `quoin write` is unavailable in the working tree, read the skeleton directly from
|
|
16
|
+
`~/.ix/filament/modules/spec-artifacts-process/skeletons/SpecReview.md`.
|
|
17
|
+
|
|
18
|
+
## Frontmatter
|
|
19
|
+
|
|
20
|
+
```yaml
|
|
21
|
+
---
|
|
22
|
+
id: SR-001 # ^[A-Z]{2,4}-[0-9]+$ — SR- default is fine; bump if SR-001 exists
|
|
23
|
+
title: "Gap analysis — <Plan-id> <slug>"
|
|
24
|
+
type: SpecReview
|
|
25
|
+
analysis: gap-analysis # the dedicated analysis value
|
|
26
|
+
scope: "plan/<Plan-id>-<slug>/, spec/matrix.md"
|
|
27
|
+
review_set: subset
|
|
28
|
+
relationships:
|
|
29
|
+
- { target: "ix://<org>/<component>/<Plan-id>", type: reviews }
|
|
30
|
+
- { target: "ix://<org>/<component>/<TestMatrix-id>", type: references }
|
|
31
|
+
---
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`<org>`/`<component>` come from `spec/spec.md` (`org`, `name`); the `<Plan-id>` and
|
|
35
|
+
`<TestMatrix-id>` from Step 1.
|
|
36
|
+
|
|
37
|
+
## Body
|
|
38
|
+
|
|
39
|
+
`## Summary` and `## Findings` are **required and validated** by `quire validate`; the others
|
|
40
|
+
are extra sections (allowed).
|
|
41
|
+
|
|
42
|
+
```markdown
|
|
43
|
+
## Summary
|
|
44
|
+
|
|
45
|
+
<1–2 sentences: what plan/matrix/code was audited and the headline result.>
|
|
46
|
+
|
|
47
|
+
## Verdict
|
|
48
|
+
|
|
49
|
+
**PASS | CONDITIONAL | FAIL** — <one line justifying the gate, per the verdict rule>.
|
|
50
|
+
|
|
51
|
+
## Findings
|
|
52
|
+
|
|
53
|
+
| ID | Severity | Summary | Refs |
|
|
54
|
+
| ------- | -------- | ------------------------------------------------ | ------------------ |
|
|
55
|
+
| FND-001 | high | Task-007 still in_progress (P0, critical path) | Task-007, FR-004 |
|
|
56
|
+
| FND-002 | high | Matrix TC-012 has no backing tagged test | TC-012, FR-006 |
|
|
57
|
+
| FND-003 | medium | `cli.ts::--force` flag has no owning requirement | cli.ts::--force |
|
|
58
|
+
|
|
59
|
+
## Coverage
|
|
60
|
+
|
|
61
|
+
- Tasks done: X / Y
|
|
62
|
+
- Matrix Test Cases backed by tagged test: X / Y
|
|
63
|
+
- Untraced behaviors / stubs: N
|
|
64
|
+
- Semantic review: ran over N requirements | skipped
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Findings table contract (validated)
|
|
68
|
+
|
|
69
|
+
- Headers EXACTLY: `ID | Severity | Summary | Refs`.
|
|
70
|
+
- `ID` matches `^FND-\d+$`; ≥1 row.
|
|
71
|
+
- `Severity` ∈ `low | medium | high`.
|
|
72
|
+
- A clean audit still records one row: `FND-001 | low | No gaps found | -`.
|
|
73
|
+
|
|
74
|
+
## Verdict rule
|
|
75
|
+
|
|
76
|
+
- **FAIL** — any incomplete/blocked task, any unbacked matrix Test Case, or any `high` finding.
|
|
77
|
+
- **CONDITIONAL** — only `medium`/`low` findings.
|
|
78
|
+
- **PASS** — no gaps (single `No gaps found` row).
|
|
79
|
+
|
|
80
|
+
## Validate
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
quire validate --scope <project_root> "reviews/**/*.md"
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Fix any validation error (frontmatter pattern, `analysis` enum, findings headers/ids/severity)
|
|
87
|
+
before reporting completion. Then tell the user the artifact path and the Verdict.
|
|
88
|
+
|
|
89
|
+
## Notes
|
|
90
|
+
|
|
91
|
+
- File name: `reviews/<YYYY-MM-DD>-<short-slug>.md` (today's real date; slug from the plan,
|
|
92
|
+
e.g. `2026-06-22-plan-002-packaging`).
|
|
93
|
+
- `reviews/` is **repo root** for this skill (deliberate); validation is path-agnostic.
|
|
94
|
+
- One run → one SpecReview doc (the `analysis: gap-analysis` lens), matching the one-doc-per-
|
|
95
|
+
analysis model used by `quoin:spec-review`.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-app-review
|
|
3
|
+
description: Review an application-type spec for completeness against UI rendering requirements and golden-path structure.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Review Application Specification
|
|
7
|
+
|
|
8
|
+
Validate a `component_type: application` spec against what the spec-editor-ui **actually renders** and the structural requirements from `specify`.
|
|
9
|
+
|
|
10
|
+
## When to Use
|
|
11
|
+
|
|
12
|
+
- After creating or updating an application spec
|
|
13
|
+
- Before submitting a spec for formal review
|
|
14
|
+
- When debugging why sections appear empty in the spec-editor-ui Application Detail view
|
|
15
|
+
|
|
16
|
+
## Process
|
|
17
|
+
|
|
18
|
+
1. **Locate spec**: Read `spec/spec.md` in the target repo. Verify `component_type: application` in frontmatter.
|
|
19
|
+
2. **Run checklist**: Evaluate every item in [references/checklist.md](references/checklist.md).
|
|
20
|
+
3. **Report findings**: Group issues by severity (FAIL = will break UI, WARN = degraded display, INFO = quality improvement).
|
|
21
|
+
4. **Fix or flag**: If instructed to fix, apply corrections. Otherwise, output the report.
|
|
22
|
+
|
|
23
|
+
## Quick Reference
|
|
24
|
+
|
|
25
|
+
The spec-editor-ui `ApplicationDetailPage` has 7 tabs. Each tab extracts data from specific sections/artifacts:
|
|
26
|
+
|
|
27
|
+
| Tab | Data Source |
|
|
28
|
+
|-----|------------|
|
|
29
|
+
| Overview | Purpose, In Scope, Out of Scope, Operational Boundaries, API Endpoints, Components (catalog), Standards (frontmatter) |
|
|
30
|
+
| Architecture | Mermaid diagrams (tagged `logical`/`deployment`), FR diagrams, Aggregated Objects (catalog) |
|
|
31
|
+
| Integration | Artifacts with `tags: [integration]` in frontmatter |
|
|
32
|
+
| Security | Trust Boundaries table, artifacts with `tags: [security]`, Standards |
|
|
33
|
+
| Requirements | StR/US/FR/NFR tables parsed from spec.md |
|
|
34
|
+
| Decisions | ADR artifacts (`type: ADR`) or inline ADR sections |
|
|
35
|
+
| Spec | Raw markdown rendering |
|
|
36
|
+
|
|
37
|
+
## Key Parsing Rules (Quire Library)
|
|
38
|
+
|
|
39
|
+
These are the **exact** parser behaviors that determine whether content renders:
|
|
40
|
+
|
|
41
|
+
- **Out of Scope**: `parseDelegations()` only recognizes `(Handled by X)` or `(Delegated to X)` patterns. Other parentheticals won't extract delegation targets.
|
|
42
|
+
- **In Scope**: `parseBulletList()` default pattern is `bold-description` (`**Title** — Description`). Plain bullets fall back to title-only.
|
|
43
|
+
- **Operational Boundaries**: `parseBulletList({ pattern: 'bold-colon' })` requires `**Name**: detail` format.
|
|
44
|
+
- **Trust Boundaries**: `parseTable()` on section "Trust Boundaries" — expects 3 columns: Role, Capabilities, Restrictions.
|
|
45
|
+
- **Mermaid tags**: `findDiagramByTag()` matches `%% @type: logical` and `%% @type: deployment` comments in mermaid blocks.
|
|
46
|
+
- **Integration tab**: Filters artifacts by `tags: [integration]` in YAML frontmatter (case-insensitive).
|
|
47
|
+
- **Security tab**: Filters artifacts by `tags: [security]` in YAML frontmatter.
|
|
48
|
+
|
|
49
|
+
## Golden Reference
|
|
50
|
+
|
|
51
|
+
Use a known well-formed application spec in your org as a comparison reference when reviewing.
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# Application Spec Review Checklist
|
|
2
|
+
|
|
3
|
+
Evaluate each item. Report as FAIL (breaks UI), WARN (degraded display), or INFO (quality).
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Frontmatter (spec.md)
|
|
8
|
+
|
|
9
|
+
- [ ] `type: master-requirements` is set
|
|
10
|
+
- [ ] `component_type: application` is set
|
|
11
|
+
- [ ] `name` matches repo name
|
|
12
|
+
- [ ] `org: <your-org>` is set
|
|
13
|
+
- [ ] `depends_on` lists all component repos
|
|
14
|
+
- [ ] `standards_alignment` includes at least `iso-iec-ieee-29148`
|
|
15
|
+
- [ ] `tags` is a non-empty array (renders in MasterRequirementsViewer)
|
|
16
|
+
- [ ] `security_critical` is set (boolean)
|
|
17
|
+
|
|
18
|
+
**Severity**: FAIL if `type` or `component_type` wrong (UI won't route to app view). WARN for missing tags.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 2. Required Sections (spec.md)
|
|
23
|
+
|
|
24
|
+
The `parseSpec()` function in `ApplicationDetailPage.tsx` extracts these by heading name. Section names must match exactly (case-insensitive heading search via Quire `section()`).
|
|
25
|
+
|
|
26
|
+
### 2.1 Purpose
|
|
27
|
+
- [ ] Section titled `Purpose` exists
|
|
28
|
+
- [ ] Contains 2-3 sentences describing what the app solves
|
|
29
|
+
|
|
30
|
+
**Severity**: WARN if missing (falls back to `repo.description`)
|
|
31
|
+
|
|
32
|
+
### 2.2 Scope Boundaries
|
|
33
|
+
- [ ] Section titled `Scope Boundaries` exists
|
|
34
|
+
|
|
35
|
+
**Severity**: WARN (card hidden if missing)
|
|
36
|
+
|
|
37
|
+
### 2.3 In Scope
|
|
38
|
+
- [ ] Subsection titled `In Scope` exists
|
|
39
|
+
- [ ] Content is a bullet list (`- Item`)
|
|
40
|
+
- [ ] For rich display: use `**Title** — Description` format per bullet
|
|
41
|
+
|
|
42
|
+
**Severity**: WARN (shows "Not defined in spec")
|
|
43
|
+
|
|
44
|
+
### 2.4 Out of Scope
|
|
45
|
+
- [ ] Subsection titled `Out of Scope` exists
|
|
46
|
+
- [ ] Each bullet uses `(Handled by X)` or `(Delegated to X)` parenthetical
|
|
47
|
+
- [ ] Do NOT use `(deferred to ...)`, `(future work)`, or other patterns — `parseDelegations()` regex: `/\((?:handled by|delegated to)\s+(.+?)\)/i`
|
|
48
|
+
|
|
49
|
+
**Severity**: WARN if section missing. INFO if delegation format wrong (items render but without arrow delegation labels).
|
|
50
|
+
|
|
51
|
+
### 2.5 Operational Boundaries
|
|
52
|
+
- [ ] Subsection titled `Operational Boundaries` exists
|
|
53
|
+
- [ ] Each bullet uses `**Name**: description` format (bold-colon pattern)
|
|
54
|
+
|
|
55
|
+
**Severity**: WARN (shows "Not defined" in Design Principles card)
|
|
56
|
+
|
|
57
|
+
### 2.6 Architecture Rationale
|
|
58
|
+
- [ ] Section titled `Architecture Rationale` exists
|
|
59
|
+
- [ ] Contains at least ADR-001
|
|
60
|
+
|
|
61
|
+
**Severity**: WARN (Decisions tab empty)
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## 3. Mermaid Diagrams
|
|
66
|
+
|
|
67
|
+
### 3.1 Logical View
|
|
68
|
+
- [ ] At least one mermaid code block exists in spec.md
|
|
69
|
+
- [ ] The primary dependency graph has `%% @type: logical` comment on line 1 (inside the fence)
|
|
70
|
+
- [ ] Falls back to first diagram if no tag — but tag is recommended
|
|
71
|
+
|
|
72
|
+
**Severity**: WARN (Architecture tab shows no logical view)
|
|
73
|
+
|
|
74
|
+
### 3.2 Deployment View
|
|
75
|
+
- [ ] A second mermaid code block with `%% @type: deployment` exists
|
|
76
|
+
- [ ] Shows namespace, pods, ingress, secrets, databases
|
|
77
|
+
|
|
78
|
+
**Severity**: WARN (Architecture tab deployment toggle hidden)
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 4. Requirement Tables (spec.md)
|
|
83
|
+
|
|
84
|
+
These tables are parsed by `parseTable()` on the section content. Column order matters (positional extraction).
|
|
85
|
+
|
|
86
|
+
### 4.1 Stakeholder Requirements
|
|
87
|
+
- [ ] Section `Stakeholder Requirements` exists with table
|
|
88
|
+
- [ ] Table columns: `ID | Title | Artifact`
|
|
89
|
+
- [ ] At least 1 StR row
|
|
90
|
+
|
|
91
|
+
### 4.2 User Stories
|
|
92
|
+
- [ ] Section `User Stories` exists with table
|
|
93
|
+
- [ ] Table columns: `ID | Title | Role | Artifact`
|
|
94
|
+
- [ ] Multiple US covering different roles
|
|
95
|
+
|
|
96
|
+
### 4.3 Functional Requirements
|
|
97
|
+
- [ ] Section `Functional Requirements` exists with table
|
|
98
|
+
- [ ] Table columns: `ID | Title | Object Type | Artifact`
|
|
99
|
+
- [ ] Required object types present:
|
|
100
|
+
- [ ] `domain` (FR-001: bounded context + ER diagram)
|
|
101
|
+
- [ ] `process` (at least 1 cross-service workflow)
|
|
102
|
+
- [ ] `configuration` (shared config across services)
|
|
103
|
+
- [ ] `integration` (consumer contract)
|
|
104
|
+
|
|
105
|
+
### 4.4 Non-Functional Requirements
|
|
106
|
+
- [ ] Section `Non-Functional Requirements` exists with table
|
|
107
|
+
- [ ] Table columns: `ID | Title | Artifact`
|
|
108
|
+
- [ ] Required NFRs:
|
|
109
|
+
- [ ] Security Constraints (NFR-001)
|
|
110
|
+
- [ ] System Reliability (NFR-002)
|
|
111
|
+
- [ ] Deployment Topology (NFR-003)
|
|
112
|
+
|
|
113
|
+
**Severity**: FAIL if tables missing (Requirements tab empty). WARN if required object types absent.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 5. Security Model (spec.md)
|
|
118
|
+
|
|
119
|
+
### 5.1 Trust Boundaries
|
|
120
|
+
- [ ] Section titled `Trust Boundaries` exists (under Security Model)
|
|
121
|
+
- [ ] Contains a table with 3 columns: Role | Capabilities | Restrictions
|
|
122
|
+
- [ ] Includes at minimum: anonymous, user, admin, operator roles
|
|
123
|
+
|
|
124
|
+
**Severity**: WARN (Security tab shows "No security trust boundaries defined")
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## 6. Artifact Frontmatter Tags
|
|
129
|
+
|
|
130
|
+
The Integration and Security tabs discover artifacts via `tags` in individual artifact YAML frontmatter, not from spec.md.
|
|
131
|
+
|
|
132
|
+
### 6.1 Integration Artifacts
|
|
133
|
+
- [ ] FR with `object: integration` also has `tags: [integration]` in frontmatter
|
|
134
|
+
- [ ] Without this tag, Integration tab shows "No integration contracts found"
|
|
135
|
+
|
|
136
|
+
### 6.2 Security Artifacts
|
|
137
|
+
- [ ] NFR-001 (Security) has `tags: [security]` in frontmatter
|
|
138
|
+
- [ ] Without this tag, Security tab falls back to parsed NFR table only (no full content rendering)
|
|
139
|
+
|
|
140
|
+
**Severity**: WARN (tabs show empty/fallback states)
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## 7. Individual Artifact Quality
|
|
145
|
+
|
|
146
|
+
For each artifact file (StR, US, FR, NFR):
|
|
147
|
+
|
|
148
|
+
### 7.1 Frontmatter
|
|
149
|
+
- [ ] `id` matches filename pattern (e.g., `FR-001`)
|
|
150
|
+
- [ ] `title` is present and descriptive
|
|
151
|
+
- [ ] `type` matches the directory (StR, US, FR, NFR)
|
|
152
|
+
|
|
153
|
+
### 7.2 Heading
|
|
154
|
+
- [ ] H1 follows pattern: `# [ID] Title`
|
|
155
|
+
- [ ] ID in brackets matches frontmatter `id`
|
|
156
|
+
|
|
157
|
+
### 7.3 Acceptance Criteria (FR, NFR)
|
|
158
|
+
- [ ] AC table exists with columns: `ID | Criteria | Verification Method`
|
|
159
|
+
- [ ] AC IDs follow pattern: `{artifact-id}-AC-{n}` (e.g., `FR-001-AC-1`)
|
|
160
|
+
|
|
161
|
+
### 7.4 Constraints (FR, NFR)
|
|
162
|
+
- [ ] Constraint table with columns: `ID | Constraint | Type | Rationale | Validation`
|
|
163
|
+
- [ ] Constraint IDs follow pattern: `{artifact-id}-CON-{n}`
|
|
164
|
+
|
|
165
|
+
### 7.5 Traceability
|
|
166
|
+
- [ ] `From:` and `Drives:` links present (or Traceability table)
|
|
167
|
+
- [ ] References are bidirectional (if FR-001 drives FR-002, FR-002 traces from FR-001)
|
|
168
|
+
|
|
169
|
+
### 7.6 User Stories
|
|
170
|
+
- [ ] AC use H3 headings with IDs: `### US-001-AC-1: Title`
|
|
171
|
+
- [ ] `From:` traces to StR, `Drives:` traces to FR
|
|
172
|
+
|
|
173
|
+
**Severity**: INFO for most. WARN if AC IDs missing (test matrix can't trace).
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## 8. Test Matrix (tests.md)
|
|
178
|
+
|
|
179
|
+
- [ ] File `spec/tests.md` exists
|
|
180
|
+
- [ ] Coverage table maps every AC to at least one TC
|
|
181
|
+
- [ ] TC entries include Type and Priority, each a single value from the
|
|
182
|
+
enforced vocabularies (see `spec-matrix/SKILL.md` § Test Case Summary —
|
|
183
|
+
`Security` is not one of them; a security test takes the Type that
|
|
184
|
+
describes how it runs)
|
|
185
|
+
- [ ] Component ownership note explains which repo runs each TC
|
|
186
|
+
- [ ] Constraint boundary tests section maps CON IDs to TCs
|
|
187
|
+
|
|
188
|
+
**Severity**: WARN if missing (no test traceability)
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## 9. Cross-Reference Integrity
|
|
193
|
+
|
|
194
|
+
- [ ] Every artifact linked in spec.md tables exists as a file
|
|
195
|
+
- [ ] Every `From:` / `Drives:` reference resolves to a real artifact ID
|
|
196
|
+
- [ ] `depends_on` in frontmatter matches Component Registry table
|
|
197
|
+
- [ ] FR relationship targets (e.g., `ix://<your-org>/...`) use valid repo names
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-dependency-analysis
|
|
3
|
+
description: Analyze dependencies and separate enablement from feature work.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Dependency & Ordering Analysis
|
|
7
|
+
|
|
8
|
+
Identify prerequisite relationships between requirements so work can be sequenced. The deliverable is a directed acyclic graph (DAG) of FRs/StRs/NFRs in **logical order**, not a schedule.
|
|
9
|
+
|
|
10
|
+
## When to use
|
|
11
|
+
|
|
12
|
+
- Before `spec-to-plan` — `spec-to-plan` consumes the DAG.
|
|
13
|
+
- After all FRs have been written and reviewed.
|
|
14
|
+
- Whenever new FRs are added that may unblock or block existing work.
|
|
15
|
+
|
|
16
|
+
## Process
|
|
17
|
+
|
|
18
|
+
1. **Identify prerequisite edges.** For each FR/StR/NFR, list every other requirement that MUST be satisfied before this one can be implemented. Express each as `A → B` (A is prerequisite to B).
|
|
19
|
+
|
|
20
|
+
2. **Classify each requirement.**
|
|
21
|
+
- **Enablement** — frameworks, abstractions, scaffolding, schema/migration, shared libs. Has no business-visible behavior on its own.
|
|
22
|
+
- **Feature** — business or user-visible behavior.
|
|
23
|
+
|
|
24
|
+
**Rule**: Enablement requirements MUST be tasked before any feature that depends on them.
|
|
25
|
+
|
|
26
|
+
3. **Verify acyclicity.** If any cycle is found, the spec is malformed — break the cycle by introducing a separation FR or merging the cyclic requirements.
|
|
27
|
+
|
|
28
|
+
4. **Produce the deliverable.** Use the template below.
|
|
29
|
+
|
|
30
|
+
## Deliverable template
|
|
31
|
+
|
|
32
|
+
Record output in `spec/analysis/dependency.md` (or as a section in `spec/spec.md` § 7 if your project keeps analysis inline).
|
|
33
|
+
|
|
34
|
+
```markdown
|
|
35
|
+
# Dependency Analysis
|
|
36
|
+
|
|
37
|
+
## Classification
|
|
38
|
+
|
|
39
|
+
| Requirement | Class | Rationale |
|
|
40
|
+
|-------------|-------|-----------|
|
|
41
|
+
| FR-001 | Enablement | Defines the auth middleware all feature FRs use |
|
|
42
|
+
| FR-002 | Enablement | Database schema for user records |
|
|
43
|
+
| FR-003 | Feature | Login flow — depends on FR-001, FR-002 |
|
|
44
|
+
| FR-004 | Feature | Password reset — depends on FR-001, FR-002 |
|
|
45
|
+
|
|
46
|
+
## Dependency Graph
|
|
47
|
+
|
|
48
|
+
```mermaid
|
|
49
|
+
graph TD
|
|
50
|
+
FR-001[FR-001: Auth middleware]
|
|
51
|
+
FR-002[FR-002: User schema]
|
|
52
|
+
FR-003[FR-003: Login flow]
|
|
53
|
+
FR-004[FR-004: Password reset]
|
|
54
|
+
FR-001 --> FR-003
|
|
55
|
+
FR-002 --> FR-003
|
|
56
|
+
FR-001 --> FR-004
|
|
57
|
+
FR-002 --> FR-004
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Topological Order (suggested implementation sequence)
|
|
61
|
+
|
|
62
|
+
1. FR-001, FR-002 (enablement, parallelizable)
|
|
63
|
+
2. FR-003, FR-004 (features, parallelizable after enablement)
|
|
64
|
+
|
|
65
|
+
## Cycles
|
|
66
|
+
|
|
67
|
+
None detected.
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Acceptance Criteria
|
|
71
|
+
|
|
72
|
+
- Every FR/StR/NFR appears in the classification table exactly once.
|
|
73
|
+
- Every edge in the graph corresponds to an explicit prerequisite — no "soft" dependencies.
|
|
74
|
+
- No cycles.
|
|
75
|
+
- Topological order respects: all enablement before any feature that depends on it.
|
|
@@ -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.
|