@agent-ix/quoin 0.14.0 → 0.15.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.
Files changed (79) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/dist/advisor/advise.d.ts +57 -0
  4. package/dist/advisor/advise.d.ts.map +1 -0
  5. package/dist/advisor/index.d.ts +10 -0
  6. package/dist/advisor/index.d.ts.map +1 -0
  7. package/dist/advisor/methods.d.ts +50 -0
  8. package/dist/advisor/methods.d.ts.map +1 -0
  9. package/dist/advisor-D35K3_iI.js +50 -0
  10. package/dist/auditor/audit.d.ts +52 -0
  11. package/dist/auditor/audit.d.ts.map +1 -0
  12. package/dist/auditor/index.d.ts +8 -0
  13. package/dist/auditor/index.d.ts.map +1 -0
  14. package/dist/{base-BIELM-Fk.js → base-CtpwIg4M.js} +2 -2
  15. package/dist/catalog.d.ts +1 -0
  16. package/dist/catalog.d.ts.map +1 -1
  17. package/dist/cli.js +1 -1
  18. package/dist/commands/catalog/list.js +2 -2
  19. package/dist/commands/catalog/methods.d.ts +12 -0
  20. package/dist/commands/catalog/methods.d.ts.map +1 -0
  21. package/dist/commands/catalog/methods.js +43 -0
  22. package/dist/commands/catalog/show.js +2 -2
  23. package/dist/commands/catalog/validate.js +2 -2
  24. package/dist/commands/config/doctor.js +1 -1
  25. package/dist/commands/config/edit.js +1 -1
  26. package/dist/commands/config/get.js +1 -1
  27. package/dist/commands/config/set.js +1 -1
  28. package/dist/commands/evidence/affirm.d.ts +17 -0
  29. package/dist/commands/evidence/affirm.d.ts.map +1 -0
  30. package/dist/commands/evidence/affirm.js +81 -0
  31. package/dist/commands/evidence/audit.d.ts +15 -0
  32. package/dist/commands/evidence/audit.d.ts.map +1 -0
  33. package/dist/commands/evidence/audit.js +192 -0
  34. package/dist/commands/evidence/gc.d.ts +13 -0
  35. package/dist/commands/evidence/gc.d.ts.map +1 -0
  36. package/dist/commands/evidence/gc.js +34 -0
  37. package/dist/commands/evidence/index.d.ts +8 -0
  38. package/dist/commands/evidence/index.d.ts.map +1 -0
  39. package/dist/commands/evidence/index.js +16 -0
  40. package/dist/commands/evidence/record.d.ts +18 -0
  41. package/dist/commands/evidence/record.d.ts.map +1 -0
  42. package/dist/commands/evidence/record.js +85 -0
  43. package/dist/commands/matrix.js +1 -1
  44. package/dist/commands/module/ensure-defaults.js +3 -3
  45. package/dist/commands/module/install.js +2 -2
  46. package/dist/commands/module/list.js +2 -2
  47. package/dist/commands/module/remove.js +2 -2
  48. package/dist/commands/review.js +1 -1
  49. package/dist/commands/to-plan.js +1 -1
  50. package/dist/commands/update.js +2 -2
  51. package/dist/commands/write.js +3 -3
  52. package/dist/evidence/index.d.ts +13 -0
  53. package/dist/evidence/index.d.ts.map +1 -0
  54. package/dist/evidence/record.d.ts +52 -0
  55. package/dist/evidence/record.d.ts.map +1 -0
  56. package/dist/evidence/store.d.ts +77 -0
  57. package/dist/evidence/store.d.ts.map +1 -0
  58. package/dist/evidence/types.d.ts +122 -0
  59. package/dist/evidence/types.d.ts.map +1 -0
  60. package/dist/evidence-BvUyw-Yv.js +171 -0
  61. package/dist/{flow-command-Cu3AeDeV.js → flow-command-BSMqxass.js} +1 -1
  62. package/dist/index.js +6 -6
  63. package/dist/{modules-BumGtAYj.js → modules-Ckfaq5p4.js} +2 -2
  64. package/dist/{plugins-DkBB_VkF.js → plugins-CLuXx2Jr.js} +1 -1
  65. package/dist/quire/contract.d.ts +82 -0
  66. package/dist/quire/contract.d.ts.map +1 -0
  67. package/dist/quire/index.d.ts +11 -0
  68. package/dist/quire/index.d.ts.map +1 -0
  69. package/dist/quire/types.d.ts +155 -0
  70. package/dist/quire/types.d.ts.map +1 -0
  71. package/dist/quire/validate.d.ts +34 -0
  72. package/dist/quire/validate.d.ts.map +1 -0
  73. package/dist/quire-MbMdffPh.js +4872 -0
  74. package/dist/schemas/coverage-v1.schema.json +191 -0
  75. package/dist/schemas/properties-v1.schema.json +134 -0
  76. package/dist/{version-4FRTZpv_.js → version-By2YFRZQ.js} +1 -1
  77. package/dist/{write-UmBcjFtj.js → write-8JJ8Dumo.js} +1 -1
  78. package/package.json +6 -2
  79. package/skills/spec-evidence-analysis/SKILL.md +64 -52
@@ -0,0 +1,191 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://agent-ix.dev/quire/schemas/output/coverage-v1.schema.json",
4
+ "title": "quire coverage --json payload (v1)",
5
+ "description": "The FR-050 coverage rollup as emitted on stdout by `quire coverage --json` and by `CoverageReport::to_json`. Hand-authored: `schemars` is banned in this crate (FR-003-AC-4) precisely so this artifact is a decision rather than a derivation, and so a payload change cannot silently rewrite its own contract. FR-008-AC-5 bans a version key in the payload, so the version lives here in the `$id` and the filename.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": [
9
+ "unbacked_rows",
10
+ "status_lies",
11
+ "untracked_symbols",
12
+ "groups",
13
+ "totals"
14
+ ],
15
+ "properties": {
16
+ "unbacked_rows": {
17
+ "type": "array",
18
+ "description": "FR-050-AC-3: reference rows answerable for trace ids no symbol backs.",
19
+ "items": { "$ref": "#/$defs/UnbackedRow" }
20
+ },
21
+ "status_lies": {
22
+ "type": "array",
23
+ "description": "FR-050-AC-4: rows whose status classes as complete while nothing backs them.",
24
+ "items": { "$ref": "#/$defs/StatusLie" }
25
+ },
26
+ "no_symbol_rows": {
27
+ "type": "array",
28
+ "description": "FR-050-AC-16 (CR-041): unbacked rows exempted from status_lies by a declared method that mints no source symbol. ABSENT — not empty — for a module declaring no `no_source_symbol` vocabulary, which is what keeps FR-050-AC-7 byte-identity.",
29
+ "items": { "$ref": "#/$defs/NoSymbolRow" }
30
+ },
31
+ "untracked_symbols": {
32
+ "type": "array",
33
+ "description": "FR-050-AC-5: source symbols whose trace tag resolves to no declared target or reference row.",
34
+ "items": { "$ref": "#/$defs/UntrackedSymbol" }
35
+ },
36
+ "groups": {
37
+ "type": "array",
38
+ "description": "FR-050-AC-6: backed/total counts per minting document and target kind.",
39
+ "items": { "$ref": "#/$defs/GroupCounts" }
40
+ },
41
+ "criteria": {
42
+ "type": "array",
43
+ "description": "FR-050-AC-13 (CR-028): per-document property-shape counts. Absent for a corpus binding no criteria.",
44
+ "items": { "$ref": "#/$defs/CriteriaCounts" }
45
+ },
46
+ "diagnostics": {
47
+ "type": "array",
48
+ "description": "CR-054: declarations that selected nothing, and why. Absent when every declaration selected something.",
49
+ "items": { "$ref": "#/$defs/CoverageDiagnostic" }
50
+ },
51
+ "obligations": {
52
+ "type": "array",
53
+ "description": "FR-053: derived obligation records, ordered by source then document then row. Absent for a model declaring no `obligations:` sources.",
54
+ "items": { "$ref": "#/$defs/Obligation" }
55
+ },
56
+ "totals": { "$ref": "#/$defs/CoverageTotals" }
57
+ },
58
+ "$defs": {
59
+ "UnbackedRow": {
60
+ "type": "object",
61
+ "additionalProperties": false,
62
+ "required": ["reference", "document", "target_ids"],
63
+ "properties": {
64
+ "reference": { "type": "string", "description": "The declaration that produced the row." },
65
+ "document": { "type": "string", "description": "Scope-relative path, `/`-separated on every platform." },
66
+ "row_id": {
67
+ "type": ["string", "null"],
68
+ "description": "The row's own id, when the declaration names a `row_id_column`."
69
+ },
70
+ "target_ids": {
71
+ "type": "array",
72
+ "items": { "type": "string" },
73
+ "description": "Trace ids the row is answerable for — its own plus the ids it references — none of which any symbol backs."
74
+ }
75
+ }
76
+ },
77
+ "StatusLie": {
78
+ "type": "object",
79
+ "additionalProperties": false,
80
+ "required": ["reference", "document", "status", "target_ids"],
81
+ "properties": {
82
+ "reference": { "type": "string" },
83
+ "document": { "type": "string" },
84
+ "row_id": { "type": ["string", "null"] },
85
+ "status": { "type": "string", "description": "The authored status value, verbatim." },
86
+ "target_ids": { "type": "array", "items": { "type": "string" } }
87
+ }
88
+ },
89
+ "NoSymbolRow": {
90
+ "type": "object",
91
+ "additionalProperties": false,
92
+ "required": ["reference", "document", "test_type", "target_ids"],
93
+ "properties": {
94
+ "reference": { "type": "string" },
95
+ "document": { "type": "string" },
96
+ "row_id": { "type": ["string", "null"] },
97
+ "test_type": { "type": "string", "description": "The declared test-type value that exempts the row." },
98
+ "target_ids": { "type": "array", "items": { "type": "string" } }
99
+ }
100
+ },
101
+ "UntrackedSymbol": {
102
+ "type": "object",
103
+ "additionalProperties": false,
104
+ "required": ["path", "symbol", "trace_id"],
105
+ "properties": {
106
+ "path": { "type": "string" },
107
+ "symbol": { "type": "string" },
108
+ "trace_id": { "type": "string" }
109
+ }
110
+ },
111
+ "GroupCounts": {
112
+ "type": "object",
113
+ "additionalProperties": false,
114
+ "required": ["document", "target", "backed", "total"],
115
+ "properties": {
116
+ "document": { "type": "string" },
117
+ "target": { "type": "string", "description": "Declared target kind the ids belong to." },
118
+ "backed": { "type": "integer", "minimum": 0 },
119
+ "total": { "type": "integer", "minimum": 0 }
120
+ }
121
+ },
122
+ "CriteriaCounts": {
123
+ "type": "object",
124
+ "additionalProperties": false,
125
+ "required": ["document", "archetype", "criteria", "property_shaped", "by_property"],
126
+ "properties": {
127
+ "document": { "type": "string" },
128
+ "archetype": { "type": "string" },
129
+ "criteria": { "type": "integer", "minimum": 0 },
130
+ "property_shaped": { "type": "integer", "minimum": 0 },
131
+ "by_property": {
132
+ "type": "object",
133
+ "additionalProperties": { "type": "integer", "minimum": 0 },
134
+ "description": "Criteria per property-shape label. Key order is deterministic (NFR-006)."
135
+ }
136
+ }
137
+ },
138
+ "CoverageDiagnostic": {
139
+ "type": "object",
140
+ "additionalProperties": false,
141
+ "required": ["declaration", "reason", "message"],
142
+ "properties": {
143
+ "declaration": { "type": "string", "description": "The declaration's name, as the model authored it." },
144
+ "reason": {
145
+ "type": "string",
146
+ "description": "Stable machine token, shared with `quire validate`'s bundle warnings. Deliberately NOT an enum here: the reason vocabulary is engine data that grows, and a schema that closed it would reject a payload from a newer engine that a consumer could otherwise read."
147
+ },
148
+ "message": { "type": "string" },
149
+ "path": { "type": ["string", "null"] }
150
+ }
151
+ },
152
+ "Obligation": {
153
+ "type": "object",
154
+ "additionalProperties": false,
155
+ "required": ["source", "id", "document", "statement", "statement_hash"],
156
+ "properties": {
157
+ "source": { "type": "string", "description": "The obligation source declaration that minted this record." },
158
+ "id": { "type": "string", "description": "The row's own id, or one rendered from `id_format`." },
159
+ "document": { "type": "string" },
160
+ "statement": { "type": "string", "description": "The normative statement, verbatim and untruncated." },
161
+ "statement_hash": {
162
+ "type": "string",
163
+ "pattern": "^[0-9a-f]{64}$",
164
+ "description": "SHA-256 of the NFC/trim/whitespace-collapsed statement. Suspect-link detection is `current != hash_at_binding` and nothing more."
165
+ },
166
+ "method": { "type": ["string", "null"], "description": "Declared verification method, trailing annotation stripped." },
167
+ "parameters": {
168
+ "type": "object",
169
+ "additionalProperties": { "type": "string" },
170
+ "description": "Declared parameters. An absent key means the cell was empty — never defaulted."
171
+ },
172
+ "criticality": { "type": ["string", "null"] }
173
+ }
174
+ },
175
+ "CoverageTotals": {
176
+ "type": "object",
177
+ "additionalProperties": false,
178
+ "required": ["backed", "total"],
179
+ "properties": {
180
+ "backed": { "type": "integer", "minimum": 0 },
181
+ "total": { "type": "integer", "minimum": 0 },
182
+ "criteria": {
183
+ "type": ["integer", "null"],
184
+ "minimum": 0,
185
+ "description": "All-or-nothing pair with `property_shaped`: both present for a corpus binding criteria, both absent otherwise. Zero is a real value; absent is not zero."
186
+ },
187
+ "property_shaped": { "type": ["integer", "null"], "minimum": 0 }
188
+ }
189
+ }
190
+ }
191
+ }
@@ -0,0 +1,134 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://agent-ix.dev/quire/schemas/output/properties-v1.schema.json",
4
+ "title": "quire properties --json payload (v1)",
5
+ "description": "The FR-052 per-criterion property-shape classification as emitted on stdout by `quire properties --json`. The envelope is assembled by `quire-cli`; every field inside a criterion comes from `AcClassification`, which this crate owns — so the contract is published here, in one place, and both sides conform to it rather than to each other. Hand-authored (`schemars` is banned, FR-003-AC-4). FR-008-AC-5 bans a version key in the payload, so the version lives in the `$id` and the filename.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": ["documents"],
9
+ "properties": {
10
+ "documents": {
11
+ "type": "array",
12
+ "items": { "$ref": "#/$defs/Document" }
13
+ }
14
+ },
15
+ "$defs": {
16
+ "Document": {
17
+ "type": "object",
18
+ "additionalProperties": false,
19
+ "required": ["document", "archetype", "criteria"],
20
+ "properties": {
21
+ "document": {
22
+ "type": "string",
23
+ "description": "The input label as the caller named it — a path, a glob expansion, or `-` for stdin."
24
+ },
25
+ "archetype": { "type": "string" },
26
+ "criteria": {
27
+ "type": "array",
28
+ "description": "Empty for a non-binding archetype (US, IT, …), which is data rather than an error.",
29
+ "items": { "$ref": "#/$defs/Criterion" }
30
+ }
31
+ }
32
+ },
33
+ "Criterion": {
34
+ "type": "object",
35
+ "additionalProperties": false,
36
+ "required": [
37
+ "row_id",
38
+ "statement",
39
+ "line",
40
+ "shape",
41
+ "property",
42
+ "extractable",
43
+ "extraction",
44
+ "domain",
45
+ "precondition",
46
+ "oracle",
47
+ "signals",
48
+ "obligation"
49
+ ],
50
+ "properties": {
51
+ "row_id": {
52
+ "type": ["string", "null"],
53
+ "description": "The criterion's own id. Null when the binding form carries none; a downstream generator cannot emit a tracking tag without it."
54
+ },
55
+ "statement": {
56
+ "type": "string",
57
+ "description": "The UNTRUNCATED statement. Every span offset indexes this field."
58
+ },
59
+ "line": { "type": ["integer", "null"], "minimum": 1 },
60
+ "shape": {
61
+ "type": "string",
62
+ "description": "The FR-047 shape axis.",
63
+ "enum": ["assertion", "obligation", "given-when-then", "unstructured"]
64
+ },
65
+ "property": {
66
+ "type": "string",
67
+ "description": "The FR-052 property-shape axis. Closed in the engine by FR-052-CON-3: a shape with no downstream generator silently drops criteria, so extension happens by declaring idiom phrases, never by adding a shape.",
68
+ "enum": [
69
+ "round-trip",
70
+ "idempotence",
71
+ "ordering",
72
+ "invariant",
73
+ "error-case",
74
+ "lifecycle",
75
+ "concurrency",
76
+ "universal",
77
+ "example",
78
+ "unclassified"
79
+ ]
80
+ },
81
+ "extractable": { "type": "boolean" },
82
+ "extraction": {
83
+ "type": "string",
84
+ "description": "CR-033: what a generator may do with this criterion. Derived from `property` and `extractable` alone.",
85
+ "enum": ["extractable", "candidate", "not-extractable"]
86
+ },
87
+ "domain": { "$ref": "#/$defs/SpanOrNull" },
88
+ "precondition": { "$ref": "#/$defs/SpanOrNull" },
89
+ "oracle": { "$ref": "#/$defs/SpanOrNull" },
90
+ "signals": {
91
+ "type": "array",
92
+ "items": { "type": "string" },
93
+ "description": "Stable ids of the signals that fired, in evaluation order. There is no confidence float — a float is unreviewable and invites threshold tuning; this trail is what makes every record re-derivable from its own output."
94
+ },
95
+ "obligation": {
96
+ "description": "FR-053. Null for a module declaring no `obligations:` source. Carries no id, statement or document: the criterion record and its enclosing document object already have all three.",
97
+ "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/CriterionObligation" }]
98
+ }
99
+ }
100
+ },
101
+ "SpanOrNull": {
102
+ "description": "A span carries both byte offsets and its own text: offsets so a consumer can assert the decomposition partitions the statement, text because handing a UTF-16 consumer raw UTF-8 byte offsets is a defect generator.",
103
+ "oneOf": [
104
+ { "type": "null" },
105
+ {
106
+ "type": "object",
107
+ "additionalProperties": false,
108
+ "required": ["start", "end", "text"],
109
+ "properties": {
110
+ "start": { "type": "integer", "minimum": 0 },
111
+ "end": { "type": "integer", "minimum": 0 },
112
+ "text": { "type": "string" }
113
+ }
114
+ }
115
+ ]
116
+ },
117
+ "CriterionObligation": {
118
+ "type": "object",
119
+ "additionalProperties": false,
120
+ "required": ["source", "statement_hash", "method", "criticality"],
121
+ "properties": {
122
+ "source": { "type": "string" },
123
+ "statement_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
124
+ "method": { "type": ["string", "null"] },
125
+ "parameters": {
126
+ "type": "object",
127
+ "additionalProperties": { "type": "string" },
128
+ "description": "Omitted entirely when the source declares no parameters or every declared cell is empty."
129
+ },
130
+ "criticality": { "type": ["string", "null"] }
131
+ }
132
+ }
133
+ }
134
+ }
@@ -11,7 +11,7 @@ function a(e) {
11
11
  return e || i();
12
12
  }
13
13
  function o() {
14
- return a("0.14.0");
14
+ return a("0.15.1");
15
15
  }
16
16
  //#endregion
17
17
  export { a as n, o as t };
@@ -1,4 +1,4 @@
1
- import { i as e } from "./base-BIELM-Fk.js";
1
+ import { i as e } from "./base-CtpwIg4M.js";
2
2
  import { n as t, r as n, t as r } from "./config-schema-Dp-vlxuR.js";
3
3
  import { ConfigService as i } from "@agent-ix/ix-cli-core";
4
4
  import { existsSync as a, readFileSync as o, statSync as s } from "node:fs";
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.14.0",
4
+ "version": "0.15.1",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -33,6 +33,9 @@
33
33
  "config": {
34
34
  "description": "Read and store quoin configuration (get, set, edit, doctor)."
35
35
  },
36
+ "evidence": {
37
+ "description": "The evidence store — what actually ran, and against which statement (record, affirm, gc)."
38
+ },
36
39
  "module": {
37
40
  "description": "Install and manage user/community spec modules (list, install, remove, ensure-defaults)."
38
41
  },
@@ -57,7 +60,7 @@
57
60
  "lint": "eslint \"src/**/*.{ts,tsx,js,jsx}\" \"tests/**/*.{ts,tsx,js,jsx}\" && pnpm run format:check",
58
61
  "format": "prettier --write .",
59
62
  "format:check": "prettier --check .",
60
- "build": "vite build",
63
+ "build": "vite build && node scripts/copy-quire-schemas.mjs",
61
64
  "clean": "rm -rf node_modules dist coverage .pnpm-store",
62
65
  "install:frozen": "pnpm install --frozen-lockfile",
63
66
  "update-lock": "pnpm install --lockfile-only",
@@ -89,6 +92,7 @@
89
92
  "@agent-ix/ix-cli-core": ">=0.12.0",
90
93
  "@agent-ix/ts-plugin-kit": ">=0.2.0",
91
94
  "@oclif/core": ">=4.13.3",
95
+ "ajv": "^8.20.0",
92
96
  "yaml": "^2.9.0",
93
97
  "zod": ">=4.4.3"
94
98
  },
@@ -1,78 +1,90 @@
1
1
  ---
2
2
  name: spec-evidence-analysis
3
- description: Define verification methods and evidence artifacts for requirements.
3
+ description: Recommend verification methods per obligation from the declared catalog, and flag mismatches with what was authored.
4
4
  ---
5
5
 
6
6
  # Verification & Evidence Strategy
7
7
 
8
- Make sure every requirement has a defined verification method and a concrete artifact that proves it was verified.
8
+ Every requirement needs a defined verification method and a concrete artifact
9
+ that proves it was verified. This skill recommends the method **from the
10
+ declared catalog**, and flags where the authored choice disagrees.
11
+
12
+ > **This skill no longer carries its own method table.** It used to: a
13
+ > skill-local list of `test | analysis | inspection | demonstration` plus a few
14
+ > evidence kinds, declared in no manifest and read by no code. The result was
15
+ > `Verification` columns defaulting to `Test` by habit, with nothing ever
16
+ > advising DAST for an attack surface, monitors for a temporal property, or
17
+ > fault injection for a reliability NFR. The methods now live in module data
18
+ > (quire-rs FR-054, `spec-artifacts-process` FR-007) and are read from there.
9
19
 
10
20
  ## When to use
11
21
 
12
- - After requirements are written but before `spec-matrix` builds the test matrix.
13
- - During `spec-review` when "how do we know this is satisfied?" is unclear.
14
- - Whenever a new NFR is added (NFRs are most prone to missing evidence).
22
+ - At **Spec Review**, to confirm each obligation's method before the matrix is built.
23
+ - At **Matrix** time, to plan which suites the chosen methods imply.
24
+ - Whenever a new NFR is added — NFRs are the ones most prone to a defaulted method.
15
25
 
16
- ## Verification methods (ISO/IEC/IEEE 29148)
26
+ ## Read the catalog, do not recall it
17
27
 
18
- | Method | Use when |
19
- |--------|----------|
20
- | `test` | The requirement is exercisable by automated or manual test execution. Default. |
21
- | `analysis` | The requirement is proven by calculation, modeling, or static reasoning (e.g. complexity bound, cryptographic argument). |
22
- | `inspection` | The requirement is satisfied by visual or structural review of the artifact (e.g. license headers, doc presence). |
23
- | `demonstration` | The requirement is satisfied by observing operation in a realistic environment without instrumentation (e.g. UX flow walkthrough). |
28
+ ```bash
29
+ quoin catalog methods # human-readable, grouped by class
30
+ quoin catalog methods --json # the merged catalog, for scripting
31
+ quoin catalog methods --class Analysis
32
+ ```
24
33
 
25
- ## Evidence artifacts
34
+ The catalog is merged first-wins across active modules, exactly as quire-rs
35
+ merges it — so the method you are advised is the method the auditor will later
36
+ check conformance against.
26
37
 
27
- | Artifact | Pairs with |
28
- |----------|------------|
29
- | `test_case` | `test` — points to a TC-XXX file or test path |
30
- | `analysis_report` | `analysis` — points to a doc/notebook |
31
- | `inspection_checklist` | `inspection` — points to a checklist file |
32
- | `demo_recording` | `demonstration` — points to a recording or scripted walkthrough |
33
- | `metric` | any — observability metric that proves runtime behavior |
34
- | `log` | any — log event proving the path executed |
38
+ ## Process
35
39
 
36
- **Rule**: Every implementation task MUST cite at least one evidence artifact. A task with no evidence is unfinishable.
40
+ 1. **Derive the obligations.** `quire coverage --json` carries them
41
+ (quire-rs FR-053): id, statement, statement hash, authored method,
42
+ criticality. Do not restate them by hand.
37
43
 
38
- ## Process
44
+ 2. **Take the deterministic recommendations first.** They come from the
45
+ catalog's `applicability` rules matched against facts about the obligation:
46
+ its statement's characteristics, its FR-052 property shape, the object types
47
+ near it, its archetype. Rules match or they do not.
39
48
 
40
- 1. **Tag every FR/StR/NFR** with `verification_method` and `evidence` fields in its frontmatter.
41
- 2. **Resolve "test" defaults**: if an FR is tagged `test`, the matching test case must already exist or be queued in `spec-matrix`.
42
- 3. **Resolve non-test methods**: for `analysis`/`inspection`/`demonstration`, name the artifact path explicitly. No "TBD".
49
+ 3. **Judge only the residue, and label it.** Where the rules are inconclusive
50
+ the advisor says so and stops rather than guessing. That is where your
51
+ judgement belongs — and it must be recorded *as* judgement. Never present an
52
+ LLM conclusion as a verdict (the ADR-0010 discipline).
43
53
 
44
- ## Deliverable template
54
+ 4. **Confirm or correct the authored method.** A flagged mismatch is advisory:
55
+ the human decides. The confirmed method lands in the spec, becomes the
56
+ obligation's method, and is what `quoin evidence` records discharge against.
45
57
 
46
- Per-requirement frontmatter (add to existing FR/StR/NFR files):
58
+ 5. **Plan the suite.** A method implies an evidence kind; a suite in
59
+ `spec/evidence/suites.md` produces that kind. A recommended method with no
60
+ suite that can produce its evidence is a gap in the plan, not a gap in the
61
+ spec.
47
62
 
48
- ```yaml
49
- verification_method: test # test | analysis | inspection | demonstration
50
- evidence:
51
- - kind: test_case
52
- ref: tests/integration/test_login.py::test_invalid_credentials
53
- - kind: metric
54
- ref: auth_failure_total
55
- ```
63
+ ## What "inconclusive" means, and why it is not a failure
56
64
 
57
- Summary deliverable in `spec/analysis/evidence.md`:
65
+ An obligation the rules cannot place is a normal outcome — the catalog's
66
+ applicability rules are deliberately narrow, because a rule that matches
67
+ everything advises nothing. Report it as inconclusive and choose a method
68
+ yourself. **Do not default to `Test` to make the report look complete**: that is
69
+ precisely the habit this skill was rebuilt to end.
58
70
 
59
- ```markdown
60
- # Verification & Evidence Summary
71
+ ## Deliverable
61
72
 
62
- | Req | Method | Artifact |
63
- |-----|--------|----------|
64
- | FR-003 | test | tests/integration/test_login.py::test_login_happy_path |
65
- | FR-010 | analysis | docs/analysis/storage-bound.md |
66
- | NFR-002 | demonstration | docs/demos/uptime-walkthrough.md |
67
- | NFR-005 | test + metric | tests/perf/test_p99_latency.py, metric `http_request_duration_seconds` |
73
+ A `SpecReview` with `analysis: evidence`, under `reviews/YY-MM-DD-<slug>.md`.
68
74
 
69
- ## Open gaps
75
+ The `Findings` table carries one row per obligation whose method needs
76
+ attention — a mismatch, or an inconclusive recommendation the author must
77
+ settle. An obligation whose authored method matches the recommendation needs no
78
+ row; a review listing every passing obligation is a review nobody reads to the
79
+ end.
70
80
 
71
- None.
81
+ ```markdown
82
+ | ID | Severity | Summary | Refs |
83
+ |----|----------|---------|------|
84
+ | FND-001 | medium | NFR-009-AC-1 is authored `Inspection`; the statement's `reliability` characteristic recommends `fault-injection` (Test). | NFR-009-AC-1 |
85
+ | FND-002 | low | FR-001-AC-9 matched no applicability rule; method chosen by judgement, not by the catalog. | FR-001-AC-9 |
72
86
  ```
73
87
 
74
- ## Acceptance Criteria
75
-
76
- - Every FR/StR/NFR has both `verification_method` and at least one `evidence` entry.
77
- - No `evidence: TBD`, no missing refs.
78
- - The summary table has zero open gaps before `spec-to-plan` is invoked.
88
+ Record the per-requirement outcome in the requirement's own `Verification`
89
+ cell — that cell **is** the obligation's method (quire-rs FR-053), so editing it
90
+ is what changes the plan. There is no separate evidence file to keep in sync.