@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.
Files changed (215) hide show
  1. package/.agents/plugins/marketplace.json +14 -0
  2. package/.claude-plugin/marketplace.json +16 -0
  3. package/.claude-plugin/plugin.json +8 -0
  4. package/.codex-plugin/plugin.json +27 -0
  5. package/.github/plugin/marketplace.json +16 -0
  6. package/LICENSE +21 -0
  7. package/README.md +266 -0
  8. package/bin/quoin.js +14 -0
  9. package/default-modules.yaml +82 -0
  10. package/dist/base-DrUMkAh1.js +137 -0
  11. package/dist/base.d.ts +23 -0
  12. package/dist/base.d.ts.map +1 -0
  13. package/dist/catalog.d.ts +32 -0
  14. package/dist/catalog.d.ts.map +1 -0
  15. package/dist/cli.d.ts +18 -0
  16. package/dist/cli.d.ts.map +1 -0
  17. package/dist/cli.js +20 -0
  18. package/dist/commands/catalog/index.d.ts +2 -0
  19. package/dist/commands/catalog/index.d.ts.map +1 -0
  20. package/dist/commands/catalog/index.js +2 -0
  21. package/dist/commands/catalog/list.d.ts +11 -0
  22. package/dist/commands/catalog/list.d.ts.map +1 -0
  23. package/dist/commands/catalog/list.js +22 -0
  24. package/dist/commands/catalog/show.d.ts +13 -0
  25. package/dist/commands/catalog/show.d.ts.map +1 -0
  26. package/dist/commands/catalog/show.js +25 -0
  27. package/dist/commands/catalog/validate.d.ts +10 -0
  28. package/dist/commands/catalog/validate.d.ts.map +1 -0
  29. package/dist/commands/catalog/validate.js +27 -0
  30. package/dist/commands/config/doctor.d.ts +7 -0
  31. package/dist/commands/config/doctor.d.ts.map +1 -0
  32. package/dist/commands/config/doctor.js +15 -0
  33. package/dist/commands/config/edit.d.ts +7 -0
  34. package/dist/commands/config/edit.d.ts.map +1 -0
  35. package/dist/commands/config/edit.js +13 -0
  36. package/dist/commands/config/get.d.ts +11 -0
  37. package/dist/commands/config/get.d.ts.map +1 -0
  38. package/dist/commands/config/get.js +20 -0
  39. package/dist/commands/config/index.d.ts +2 -0
  40. package/dist/commands/config/index.d.ts.map +1 -0
  41. package/dist/commands/config/index.js +2 -0
  42. package/dist/commands/config/set.d.ts +12 -0
  43. package/dist/commands/config/set.d.ts.map +1 -0
  44. package/dist/commands/config/set.js +26 -0
  45. package/dist/commands/matrix.d.ts +14 -0
  46. package/dist/commands/matrix.d.ts.map +1 -0
  47. package/dist/commands/matrix.js +15 -0
  48. package/dist/commands/module/ensure-defaults.d.ts +8 -0
  49. package/dist/commands/module/ensure-defaults.d.ts.map +1 -0
  50. package/dist/commands/module/ensure-defaults.js +17 -0
  51. package/dist/commands/module/index.d.ts +2 -0
  52. package/dist/commands/module/index.d.ts.map +1 -0
  53. package/dist/commands/module/index.js +2 -0
  54. package/dist/commands/module/install.d.ts +11 -0
  55. package/dist/commands/module/install.d.ts.map +1 -0
  56. package/dist/commands/module/install.js +22 -0
  57. package/dist/commands/module/list.d.ts +8 -0
  58. package/dist/commands/module/list.d.ts.map +1 -0
  59. package/dist/commands/module/list.js +13 -0
  60. package/dist/commands/module/remove.d.ts +10 -0
  61. package/dist/commands/module/remove.d.ts.map +1 -0
  62. package/dist/commands/module/remove.js +16 -0
  63. package/dist/commands/plugin/deprecation.d.ts +10 -0
  64. package/dist/commands/plugin/deprecation.d.ts.map +1 -0
  65. package/dist/commands/plugin/ensure-defaults.d.ts +8 -0
  66. package/dist/commands/plugin/ensure-defaults.d.ts.map +1 -0
  67. package/dist/commands/plugin/ensure-defaults.js +12 -0
  68. package/dist/commands/plugin/index.d.ts +2 -0
  69. package/dist/commands/plugin/index.d.ts.map +1 -0
  70. package/dist/commands/plugin/index.js +2 -0
  71. package/dist/commands/plugin/install.d.ts +8 -0
  72. package/dist/commands/plugin/install.d.ts.map +1 -0
  73. package/dist/commands/plugin/install.js +12 -0
  74. package/dist/commands/plugin/list.d.ts +8 -0
  75. package/dist/commands/plugin/list.d.ts.map +1 -0
  76. package/dist/commands/plugin/list.js +12 -0
  77. package/dist/commands/plugin/remove.d.ts +8 -0
  78. package/dist/commands/plugin/remove.d.ts.map +1 -0
  79. package/dist/commands/plugin/remove.js +12 -0
  80. package/dist/commands/review.d.ts +14 -0
  81. package/dist/commands/review.d.ts.map +1 -0
  82. package/dist/commands/review.js +15 -0
  83. package/dist/commands/to-plan.d.ts +14 -0
  84. package/dist/commands/to-plan.d.ts.map +1 -0
  85. package/dist/commands/to-plan.js +15 -0
  86. package/dist/commands/update.d.ts +13 -0
  87. package/dist/commands/update.d.ts.map +1 -0
  88. package/dist/commands/update.js +34 -0
  89. package/dist/commands/write.d.ts +16 -0
  90. package/dist/commands/write.d.ts.map +1 -0
  91. package/dist/commands/write.js +33 -0
  92. package/dist/config-schema-Dp-vlxuR.js +13 -0
  93. package/dist/config-schema.d.ts +52 -0
  94. package/dist/config-schema.d.ts.map +1 -0
  95. package/dist/deprecation-fRxUHoxv.js +4 -0
  96. package/dist/flow-command-SMjCSOFg.js +88 -0
  97. package/dist/flow-command.d.ts +25 -0
  98. package/dist/flow-command.d.ts.map +1 -0
  99. package/dist/flows.d.ts +7 -0
  100. package/dist/flows.d.ts.map +1 -0
  101. package/dist/index.d.ts +11 -0
  102. package/dist/index.d.ts.map +1 -0
  103. package/dist/index.js +9 -0
  104. package/dist/modules-CW8pBK41.js +22 -0
  105. package/dist/modules.d.ts +10 -0
  106. package/dist/modules.d.ts.map +1 -0
  107. package/dist/org.d.ts +61 -0
  108. package/dist/org.d.ts.map +1 -0
  109. package/dist/plugins-GSxafyD3.js +77 -0
  110. package/dist/plugins.d.ts +13 -0
  111. package/dist/plugins.d.ts.map +1 -0
  112. package/dist/version-_1nY4KyJ.js +17 -0
  113. package/dist/version.d.ts +3 -0
  114. package/dist/version.d.ts.map +1 -0
  115. package/dist/write-CQAitcI5.js +156 -0
  116. package/dist/write.d.ts +28 -0
  117. package/dist/write.d.ts.map +1 -0
  118. package/package.json +119 -0
  119. package/skills/gap-analysis/SKILL.md +97 -0
  120. package/skills/gap-analysis/references/step-1-target-selection.md +53 -0
  121. package/skills/gap-analysis/references/step-2-plan-completion.md +49 -0
  122. package/skills/gap-analysis/references/step-3-matrix-verification.md +54 -0
  123. package/skills/gap-analysis/references/step-4-underspecified-code.md +63 -0
  124. package/skills/gap-analysis/references/step-5-semantic-review.md +51 -0
  125. package/skills/gap-analysis/references/step-6-specreview-artifact.md +95 -0
  126. package/skills/spec-app-review/SKILL.md +51 -0
  127. package/skills/spec-app-review/references/checklist.md +197 -0
  128. package/skills/spec-dependency-analysis/SKILL.md +75 -0
  129. package/skills/spec-ears-analysis/SKILL.md +89 -0
  130. package/skills/spec-evidence-analysis/SKILL.md +78 -0
  131. package/skills/spec-failure-domain-analysis/SKILL.md +44 -0
  132. package/skills/spec-ideation/SKILL.md +46 -0
  133. package/skills/spec-integrity-analysis/SKILL.md +47 -0
  134. package/skills/spec-matrix/SKILL.md +168 -0
  135. package/skills/spec-matrix/assets/test-cases/TC-001.md +35 -0
  136. package/skills/spec-matrix/assets/test-cases/TC-002.md +37 -0
  137. package/skills/spec-matrix/assets/test-cases/TC-006.md +50 -0
  138. package/skills/spec-matrix/assets/test-matrix-example.md +104 -0
  139. package/skills/spec-matrix/assets/test-matrix-template.md +123 -0
  140. package/skills/spec-matrix/workflow-assets/skills/matrix/SKILL.md +35 -0
  141. package/skills/spec-matrix/workflow-assets/skills/matrix/scripts/invariants.js +1 -0
  142. package/skills/spec-matrix/workflow-assets/skills/matrix/templates/report/default.md +30 -0
  143. package/skills/spec-matrix/workflow-assets/skills/matrix/workflows/matrix/def.yaml +82 -0
  144. package/skills/spec-object-review/SKILL.md +125 -0
  145. package/skills/spec-object-review/references/object-type-guide.md +118 -0
  146. package/skills/spec-review/SKILL.md +71 -0
  147. package/skills/spec-review/references/checklist.md +50 -0
  148. package/skills/spec-review/workflow-assets/skills/review/SKILL.md +96 -0
  149. package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +60 -0
  150. package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +68 -0
  151. package/skills/spec-risk-complexity-analysis/SKILL.md +77 -0
  152. package/skills/spec-scope-boundary-analysis/SKILL.md +86 -0
  153. package/skills/spec-security-analysis/SKILL.md +84 -0
  154. package/skills/spec-security-analysis/assets/security-analysis-example.md +89 -0
  155. package/skills/spec-security-analysis/assets/security-analysis-template.md +73 -0
  156. package/skills/spec-security-analysis/references/component-type-mapping.md +161 -0
  157. package/skills/spec-security-analysis/references/gdpr/ChII-Principles.md +58 -0
  158. package/skills/spec-security-analysis/references/gdpr/ChIII-DataSubjectRights.md +84 -0
  159. package/skills/spec-security-analysis/references/gdpr/ChIV-ControllerProcessor.md +83 -0
  160. package/skills/spec-security-analysis/references/gdpr/ChV-DataTransfers.md +62 -0
  161. package/skills/spec-security-analysis/references/gdpr/index.md +54 -0
  162. package/skills/spec-security-analysis/references/iso27001/A5-OrganizationalControls.md +64 -0
  163. package/skills/spec-security-analysis/references/iso27001/A6-PeopleControls.md +30 -0
  164. package/skills/spec-security-analysis/references/iso27001/A7-PhysicalControls.md +35 -0
  165. package/skills/spec-security-analysis/references/iso27001/A8-TechnologicalControls.md +66 -0
  166. package/skills/spec-security-analysis/references/iso27001/index.md +43 -0
  167. package/skills/spec-security-analysis/references/nist-800-53/AC-AccessControl.md +57 -0
  168. package/skills/spec-security-analysis/references/nist-800-53/AU-AuditAccountability.md +49 -0
  169. package/skills/spec-security-analysis/references/nist-800-53/CM-ConfigurationManagement.md +36 -0
  170. package/skills/spec-security-analysis/references/nist-800-53/IA-IdentificationAuthentication.md +44 -0
  171. package/skills/spec-security-analysis/references/nist-800-53/SA-SystemServicesAcquisition.md +50 -0
  172. package/skills/spec-security-analysis/references/nist-800-53/SC-SystemCommunications.md +53 -0
  173. package/skills/spec-security-analysis/references/nist-800-53/SI-SystemInformationIntegrity.md +52 -0
  174. package/skills/spec-security-analysis/references/nist-800-53/index.md +58 -0
  175. package/skills/spec-security-analysis/references/owasp-asvs/V1-Architecture.md +33 -0
  176. package/skills/spec-security-analysis/references/owasp-asvs/V10-MaliciousCode.md +33 -0
  177. package/skills/spec-security-analysis/references/owasp-asvs/V11-BusinessLogic.md +32 -0
  178. package/skills/spec-security-analysis/references/owasp-asvs/V12-Files.md +34 -0
  179. package/skills/spec-security-analysis/references/owasp-asvs/V13-API.md +34 -0
  180. package/skills/spec-security-analysis/references/owasp-asvs/V14-Configuration.md +35 -0
  181. package/skills/spec-security-analysis/references/owasp-asvs/V2-Authentication.md +36 -0
  182. package/skills/spec-security-analysis/references/owasp-asvs/V3-SessionManagement.md +35 -0
  183. package/skills/spec-security-analysis/references/owasp-asvs/V4-AccessControl.md +39 -0
  184. package/skills/spec-security-analysis/references/owasp-asvs/V5-Validation.md +37 -0
  185. package/skills/spec-security-analysis/references/owasp-asvs/V6-Cryptography.md +34 -0
  186. package/skills/spec-security-analysis/references/owasp-asvs/V7-ErrorLogging.md +37 -0
  187. package/skills/spec-security-analysis/references/owasp-asvs/V8-DataProtection.md +34 -0
  188. package/skills/spec-security-analysis/references/owasp-asvs/V9-Communication.md +32 -0
  189. package/skills/spec-security-analysis/references/owasp-asvs/index.md +59 -0
  190. package/skills/spec-security-analysis/references/soc2/CC1-ControlEnvironment.md +31 -0
  191. package/skills/spec-security-analysis/references/soc2/CC2-CommunicationInformation.md +27 -0
  192. package/skills/spec-security-analysis/references/soc2/CC3-RiskAssessment.md +29 -0
  193. package/skills/spec-security-analysis/references/soc2/CC4-MonitoringActivities.md +27 -0
  194. package/skills/spec-security-analysis/references/soc2/CC5-ControlActivities.md +28 -0
  195. package/skills/spec-security-analysis/references/soc2/CC6-LogicalPhysicalAccess.md +45 -0
  196. package/skills/spec-security-analysis/references/soc2/CC7-SystemOperations.md +42 -0
  197. package/skills/spec-security-analysis/references/soc2/CC8-ChangeManagement.md +32 -0
  198. package/skills/spec-security-analysis/references/soc2/CC9-RiskMitigation.md +34 -0
  199. package/skills/spec-security-analysis/references/soc2/index.md +46 -0
  200. package/skills/spec-security-analysis/references/standards-index.md +46 -0
  201. package/skills/spec-to-plan/SKILL.md +75 -0
  202. package/skills/spec-to-plan/references/step-0-plan-selection.md +121 -0
  203. package/skills/spec-to-plan/references/step-1-analysis.md +88 -0
  204. package/skills/spec-to-plan/references/step-2-test-plan.md +43 -0
  205. package/skills/spec-to-plan/references/step-3-execution-plan.md +218 -0
  206. package/skills/spec-to-plan/workflow-assets/skills/to-plan/SKILL.md +35 -0
  207. package/skills/spec-to-plan/workflow-assets/skills/to-plan/scripts/invariants.js +1 -0
  208. package/skills/spec-to-plan/workflow-assets/skills/to-plan/templates/implementation-plan/default.md +44 -0
  209. package/skills/spec-to-plan/workflow-assets/skills/to-plan/workflows/to-plan/def.yaml +85 -0
  210. package/skills/specify/SKILL.md +154 -0
  211. package/skills/specify/assets/app-spec-template.md +143 -0
  212. package/skills/specify/assets/spec-template.md +299 -0
  213. package/skills/specify/references/integration-tests.md +72 -0
  214. package/skills/specify/references/us-to-fr.md +40 -0
  215. 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.