@agent-ix/quoin 0.3.6 → 0.3.7
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/default-modules.yaml +2 -2
- package/package.json +1 -1
- package/skills/spec-review/SKILL.md +42 -13
- package/skills/spec-review/workflow-assets/skills/review/SKILL.md +66 -5
- package/skills/spec-review/workflow-assets/skills/review/scripts/invariants.js +60 -1
- package/skills/spec-review/workflow-assets/skills/review/workflows/review/def.yaml +28 -42
- package/skills/spec-review/workflow-assets/skills/review/templates/report/default.md +0 -30
package/default-modules.yaml
CHANGED
|
@@ -28,13 +28,13 @@ entries:
|
|
|
28
28
|
ref: v0.2.0
|
|
29
29
|
|
|
30
30
|
- name: spec-artifacts-process
|
|
31
|
-
version: "0.
|
|
31
|
+
version: "0.3.0"
|
|
32
32
|
defaultEnabled: true
|
|
33
33
|
source:
|
|
34
34
|
type: git-subdir
|
|
35
35
|
url: agent-ix/spec-artifacts-process
|
|
36
36
|
path: spec_artifacts_process
|
|
37
|
-
ref: v0.
|
|
37
|
+
ref: v0.3.0
|
|
38
38
|
|
|
39
39
|
- name: spec-objects-business
|
|
40
40
|
version: "0.3.0"
|
package/package.json
CHANGED
|
@@ -11,27 +11,56 @@ Use this skill to validate requirements artefacts before implementation.
|
|
|
11
11
|
|
|
12
12
|
See **[references/checklist.md](references/checklist.md)** for the detailed quality gates.
|
|
13
13
|
|
|
14
|
+
## Choose the review set
|
|
15
|
+
|
|
16
|
+
Before reviewing, present these options to the user and let them choose:
|
|
17
|
+
|
|
18
|
+
- **base** — the **Checklist** only: ID formats, US/FR/TC quality, and the six coverage
|
|
19
|
+
rules. No analysis skills.
|
|
20
|
+
- **all** — `base` plus all six analyses below.
|
|
21
|
+
- **subset** — `base` plus the analyses the user picks from the six below.
|
|
22
|
+
|
|
23
|
+
The six analyses:
|
|
24
|
+
|
|
25
|
+
| Analysis | Skill |
|
|
26
|
+
| --- | --- |
|
|
27
|
+
| failure-domain | `spec-failure-domain-analysis` |
|
|
28
|
+
| integrity | `spec-integrity-analysis` |
|
|
29
|
+
| dependency | `spec-dependency-analysis` |
|
|
30
|
+
| evidence | `spec-evidence-analysis` |
|
|
31
|
+
| risk-complexity | `spec-risk-complexity-analysis` |
|
|
32
|
+
| scope-boundary | `spec-scope-boundary-analysis` |
|
|
33
|
+
|
|
14
34
|
## Process
|
|
15
35
|
|
|
16
|
-
1. Automated Checks:
|
|
36
|
+
1. Automated Checks (always — part of `base`):
|
|
17
37
|
- Validate ID formats (US/FR/TC/AC/CON).
|
|
18
38
|
- Detect duplicates or gaps.
|
|
19
39
|
- Validation link integrity.
|
|
20
|
-
2.
|
|
40
|
+
2. Base Review (always):
|
|
21
41
|
- Read each artifact.
|
|
22
42
|
- Verify against the **Checklist**.
|
|
23
43
|
- Verify Test Coverage (6 Rules).
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
44
|
+
3. Selected Analyses:
|
|
45
|
+
- Run each analysis the user chose. Prefer running them **in parallel**.
|
|
46
|
+
- **Fetch the template from quoin** once with `quoin write --types SpecReview` — use its
|
|
47
|
+
skeleton + schema as the contract (do not invent the format).
|
|
48
|
+
- Write **one `SpecReview` document per analysis** to `spec/reviews/<analysis>.md`
|
|
49
|
+
(plus `spec/reviews/base.md` for the base checklist). Findings go in a validated
|
|
50
|
+
`## Findings` table (`| ID | Severity | Summary | Refs |`, `FND-NNN` ids, Severity ∈
|
|
51
|
+
`low`/`medium`/`high`).
|
|
52
|
+
4. Validate + record:
|
|
53
|
+
- Run `quire validate --scope <repo> "spec/**/*.md"` and fix any errors.
|
|
54
|
+
- The docs sync into filament-core as `SpecReview` artifacts; do not proceed to
|
|
55
|
+
implementation until reviewed.
|
|
56
|
+
|
|
57
|
+
## Enforced runs (workflow mode)
|
|
58
|
+
|
|
59
|
+
`quoin review` drives this through `ix-flow`, which **records the chosen set and hard-blocks
|
|
60
|
+
acceptance until every selected analysis has produced a validated `SpecReview` doc** (the
|
|
61
|
+
`selected_analyses_covered` gate). Use it when you want the choice enforced rather than
|
|
62
|
+
trusted to discipline. The per-analysis `SpecReview` structure + the findings table are
|
|
63
|
+
defined in the workflow skill (`workflow-assets/skills/review/SKILL.md`).
|
|
35
64
|
|
|
36
65
|
## Common Issues
|
|
37
66
|
|
|
@@ -13,19 +13,80 @@ Use this skill for a full or multi-artifact spec review before implementation, r
|
|
|
13
13
|
|
|
14
14
|
## What It Does
|
|
15
15
|
|
|
16
|
-
Run a composite specification review. The workflow definition is the source of truth for
|
|
16
|
+
Run a composite specification review. The workflow definition is the source of truth for
|
|
17
|
+
phases, gates, item schemas, and recipes. The review produces **one validated `SpecReview`
|
|
18
|
+
document per analysis** under `spec/reviews/`, rather than a single freeform report.
|
|
17
19
|
|
|
18
20
|
## Workflow Behavior
|
|
19
21
|
|
|
20
22
|
- Start from the workflow status and follow reported next actions.
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
-
|
|
23
|
+
- **intake — offer the review set.** Before advancing, present the choice to the user and
|
|
24
|
+
record it in the `request` interview as `review_set` plus `selected_analyses`:
|
|
25
|
+
- `base` — the skill checklist only (ID formats, US/FR/TC quality, the six coverage
|
|
26
|
+
rules). No analysis skills. `selected_analyses` is empty.
|
|
27
|
+
- `all` — `base` plus all six analyses: `failure-domain`, `integrity`, `dependency`,
|
|
28
|
+
`evidence`, `risk-complexity`, `scope-boundary`.
|
|
29
|
+
- `subset` — `base` plus the analyses the user picks from those six.
|
|
30
|
+
- **analyses_run — run the selected set, one SpecReview doc each.** Run each selected
|
|
31
|
+
analysis (the matching `spec-*-analysis` skill). Prefer running them **in parallel** —
|
|
32
|
+
each writes its own file, so there is no contention.
|
|
33
|
+
- **Guardrail — fetch the template from quoin (do not invent the format).** Once, run
|
|
34
|
+
`quoin write <repo> --types SpecReview` and use the emitted skeleton + schema as the
|
|
35
|
+
authoritative contract. Reuse that one contract for every analysis doc.
|
|
36
|
+
- **Direct-author** a `SpecReview` markdown document per analysis to
|
|
37
|
+
`spec/reviews/<analysis>.md` from that template. `base` renders a single
|
|
38
|
+
`spec/reviews/base.md` with `analysis: base`.
|
|
39
|
+
- **reviews_rendered — validate (guardrail).** Always run the quire validation command (the
|
|
40
|
+
calling tool emits it, e.g. `quire validate --scope <repo> "spec/**/*.md"`). Fix any finding-table / severity
|
|
41
|
+
/ id errors it reports. Only once a SpecReview doc validates, record it:
|
|
42
|
+
`add-item review_doc --item '{"id":"RD-<analysis>","analysis":"<analysis>","path":"spec/reviews/<analysis>.md"}'`
|
|
43
|
+
(the item `id` must be non-empty). These items drive the coverage gate.
|
|
44
|
+
- Use recipes for deterministic command chains, but preserve the human gate for acceptance.
|
|
45
|
+
|
|
46
|
+
## SpecReview document structure
|
|
47
|
+
|
|
48
|
+
The **authoritative** template comes from `quoin write --types SpecReview` (fetch it; do not
|
|
49
|
+
hand-copy). The structure below is a reference for what that skeleton contains — each
|
|
50
|
+
`spec/reviews/<analysis>.md` is a `SpecReview` artifact (archetype in
|
|
51
|
+
`spec-artifacts-process`):
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
---
|
|
55
|
+
id: SR-001
|
|
56
|
+
title: "<analysis> review of <scope>"
|
|
57
|
+
type: SpecReview
|
|
58
|
+
analysis: <failure-domain|integrity|dependency|evidence|risk-complexity|scope-boundary|base>
|
|
59
|
+
scope: <spec paths / ids>
|
|
60
|
+
review_set: <base|all|subset>
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Summary
|
|
64
|
+
|
|
65
|
+
<one or two sentences on what this analysis found>
|
|
66
|
+
|
|
67
|
+
## Findings
|
|
68
|
+
|
|
69
|
+
| ID | Severity | Summary | Refs |
|
|
70
|
+
| --- | --- | --- | --- |
|
|
71
|
+
| FND-001 | medium | <one-line finding> | FR-014 |
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The `## Findings` table is **validated by quire**: exact columns `[ID, Severity, Summary,
|
|
75
|
+
Refs]`, at least one row, `FND-NNN` ids, and `Severity` must be one of `low`/`medium`/`high`.
|
|
76
|
+
An analysis that found nothing still renders a doc; record that as a single
|
|
77
|
+
`FND-001 | low | No issues found | —` row (or state it in `## Summary`).
|
|
78
|
+
|
|
79
|
+
## Coverage gate
|
|
80
|
+
|
|
81
|
+
The final `validated → accepted` transition enforces `selected_analyses_covered`: the run
|
|
82
|
+
cannot be accepted until every selected analysis has a recorded `review_doc`. If it reports
|
|
83
|
+
`selected_analyses_not_run` with a `missing` list, render + validate + record those analyses
|
|
84
|
+
before retrying acceptance. `base` passes with no analyses required.
|
|
24
85
|
|
|
25
86
|
## Acceptance Criteria
|
|
26
87
|
|
|
27
88
|
- AC-1: Reviews structural integrity, traceability, coverage, and readiness across selected artifacts.
|
|
28
|
-
- AC-2:
|
|
89
|
+
- AC-2: Produces one validated `SpecReview` doc per selected analysis before acceptance.
|
|
29
90
|
- AC-3: Stops at acceptance with findings and recommended next workflows rather than making broad edits.
|
|
30
91
|
|
|
31
92
|
## Boundaries
|
|
@@ -1 +1,60 @@
|
|
|
1
|
-
|
|
1
|
+
import { specInvariants } from "../../../dist/index.js";
|
|
2
|
+
|
|
3
|
+
// Canonical "all" set — the six analyses named in the spec-review skill.
|
|
4
|
+
const ALL_ANALYSES = [
|
|
5
|
+
"failure-domain",
|
|
6
|
+
"integrity",
|
|
7
|
+
"dependency",
|
|
8
|
+
"evidence",
|
|
9
|
+
"risk-complexity",
|
|
10
|
+
"scope-boundary",
|
|
11
|
+
];
|
|
12
|
+
|
|
13
|
+
const norm = (value) =>
|
|
14
|
+
String(value ?? "")
|
|
15
|
+
.trim()
|
|
16
|
+
.toLowerCase()
|
|
17
|
+
.replace(/^spec-/, "")
|
|
18
|
+
.replace(/-analysis$/, "");
|
|
19
|
+
|
|
20
|
+
function findRequest(instance) {
|
|
21
|
+
const items = instance.items?.operation_request ?? [];
|
|
22
|
+
return (
|
|
23
|
+
items.find((item) => item && item.interviewId === "request") ?? items[0]
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
// Hard check (final gate): every selected analysis must have a recorded
|
|
28
|
+
// `review_doc` (a rendered + quire-validated SpecReview doc on disk) before
|
|
29
|
+
// the run can be accepted. 'base' selects nothing, so it passes trivially;
|
|
30
|
+
// 'all' expands to the canonical six when the agent did not echo the list.
|
|
31
|
+
const selectedAnalysesCovered = ({ instance }) => {
|
|
32
|
+
const request = findRequest(instance);
|
|
33
|
+
const reviewSet = norm(request?.review_set);
|
|
34
|
+
let selected = Array.isArray(request?.selected_analyses)
|
|
35
|
+
? request.selected_analyses.map(norm).filter(Boolean)
|
|
36
|
+
: [];
|
|
37
|
+
if (reviewSet === "all" && selected.length === 0) {
|
|
38
|
+
selected = [...ALL_ANALYSES];
|
|
39
|
+
}
|
|
40
|
+
if (selected.length === 0) return true;
|
|
41
|
+
|
|
42
|
+
const ran = new Set(
|
|
43
|
+
(instance.items?.review_doc ?? [])
|
|
44
|
+
.map((doc) => norm(doc?.analysis))
|
|
45
|
+
.filter(Boolean),
|
|
46
|
+
);
|
|
47
|
+
const missing = selected.filter((analysis) => !ran.has(analysis));
|
|
48
|
+
return (
|
|
49
|
+
missing.length === 0 || {
|
|
50
|
+
ok: false,
|
|
51
|
+
code: "selected_analyses_not_run",
|
|
52
|
+
details: { reviewSet, selected, missing },
|
|
53
|
+
}
|
|
54
|
+
);
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
export const invariants = {
|
|
58
|
+
...specInvariants,
|
|
59
|
+
selected_analyses_covered: selectedAnalysesCovered,
|
|
60
|
+
};
|
|
@@ -1,81 +1,67 @@
|
|
|
1
1
|
name: review
|
|
2
|
-
version: 0.
|
|
3
|
-
description: Run a composite specification review.
|
|
2
|
+
version: 0.2.0
|
|
3
|
+
description: Run a composite specification review producing validated SpecReview docs.
|
|
4
4
|
initialPhase: intake
|
|
5
5
|
phases:
|
|
6
6
|
- { name: intake }
|
|
7
|
-
- { name:
|
|
8
|
-
- { name:
|
|
7
|
+
- { name: analyses_run }
|
|
8
|
+
- { name: reviews_rendered }
|
|
9
9
|
- { name: validated }
|
|
10
10
|
- { name: accepted, terminal: true }
|
|
11
11
|
transitions:
|
|
12
12
|
- from: intake
|
|
13
|
-
to:
|
|
13
|
+
to: analyses_run
|
|
14
14
|
invariants:
|
|
15
15
|
- "interview.complete:request"
|
|
16
16
|
defaultGate: auto
|
|
17
|
-
- from:
|
|
18
|
-
to:
|
|
17
|
+
- from: analyses_run
|
|
18
|
+
to: reviews_rendered
|
|
19
19
|
invariants: []
|
|
20
20
|
defaultGate: auto
|
|
21
|
-
- from:
|
|
21
|
+
- from: reviews_rendered
|
|
22
22
|
to: validated
|
|
23
|
-
invariants:
|
|
24
|
-
- "artifact.frontmatter_valid:report"
|
|
23
|
+
invariants: []
|
|
25
24
|
defaultGate: auto
|
|
26
25
|
- from: validated
|
|
27
26
|
to: accepted
|
|
28
|
-
invariants:
|
|
27
|
+
invariants:
|
|
28
|
+
- "selected_analyses_covered"
|
|
29
29
|
defaultGate: hitl
|
|
30
30
|
itemSchemas:
|
|
31
31
|
operation_request: {}
|
|
32
|
-
|
|
33
|
-
|
|
32
|
+
# One per analysis the agent ran + validated: a SpecReview doc on disk.
|
|
33
|
+
review_doc:
|
|
34
|
+
required: [analysis, path]
|
|
34
35
|
properties:
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
title: { type: string }
|
|
38
|
-
scope: { type: string }
|
|
36
|
+
analysis: { type: string }
|
|
37
|
+
path: { type: string }
|
|
39
38
|
linkSchemas: {}
|
|
40
39
|
interviews:
|
|
41
40
|
request:
|
|
42
41
|
itemType: operation_request
|
|
43
42
|
completenessRule: all_required
|
|
44
43
|
questions:
|
|
45
|
-
- key: artifact_id
|
|
46
|
-
prompt: "Report id, for example REPORT-001."
|
|
47
|
-
type: text
|
|
48
|
-
required: true
|
|
49
|
-
- key: title
|
|
50
|
-
prompt: "Report title."
|
|
51
|
-
type: text
|
|
52
|
-
required: true
|
|
53
44
|
- key: scope
|
|
54
|
-
prompt: "Spec paths, requirement ids, or graph scope to
|
|
45
|
+
prompt: "Spec paths, requirement ids, or graph scope to review."
|
|
55
46
|
type: text
|
|
56
47
|
required: true
|
|
57
|
-
- key:
|
|
58
|
-
prompt: "
|
|
59
|
-
type:
|
|
60
|
-
|
|
61
|
-
- key: findings
|
|
62
|
-
prompt: "Findings, gaps, or result summary."
|
|
63
|
-
type: text
|
|
48
|
+
- key: review_set
|
|
49
|
+
prompt: "Review set: 'base' (skill checklist only), 'all' (the six analyses), or 'subset'."
|
|
50
|
+
type: enum
|
|
51
|
+
options: [base, all, subset]
|
|
64
52
|
required: true
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
phase: report_rendered
|
|
70
|
-
frontmatterSchema: OperationReportSchema
|
|
53
|
+
- key: selected_analyses
|
|
54
|
+
prompt: "Analyses to run as a list, drawn from: failure-domain, integrity, dependency, evidence, risk-complexity, scope-boundary. Use all six for 'all'; the chosen ones for 'subset'; leave empty for 'base'."
|
|
55
|
+
type: list<text>
|
|
56
|
+
required: false
|
|
71
57
|
recipes:
|
|
72
58
|
run-to-review:
|
|
73
|
-
description: Record inputs,
|
|
59
|
+
description: Record inputs, then advance through analyses, rendering, validation, to acceptance.
|
|
74
60
|
steps:
|
|
75
61
|
- command: advance
|
|
76
|
-
to:
|
|
62
|
+
to: analyses_run
|
|
77
63
|
- command: advance
|
|
78
|
-
to:
|
|
64
|
+
to: reviews_rendered
|
|
79
65
|
- command: advance
|
|
80
66
|
to: validated
|
|
81
67
|
- command: advance
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
type: spec-review
|
|
3
|
-
id: "{{items.operation_request.request.artifact_id}}"
|
|
4
|
-
title: "{{items.operation_request.request.title}}"
|
|
5
|
-
scope: "{{items.operation_request.request.scope}}"
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# {{items.operation_request.request.artifact_id}}: {{items.operation_request.request.title}}
|
|
9
|
-
|
|
10
|
-
## Operation
|
|
11
|
-
|
|
12
|
-
Run a composite specification review.
|
|
13
|
-
|
|
14
|
-
## Scope
|
|
15
|
-
|
|
16
|
-
{{items.operation_request.request.scope}}
|
|
17
|
-
|
|
18
|
-
## Evidence
|
|
19
|
-
|
|
20
|
-
{{items.operation_request.request.evidence}}
|
|
21
|
-
|
|
22
|
-
## Findings
|
|
23
|
-
|
|
24
|
-
{{items.operation_request.request.findings}}
|
|
25
|
-
|
|
26
|
-
## Acceptance Criteria
|
|
27
|
-
|
|
28
|
-
- Evidence is recorded before conclusions.
|
|
29
|
-
- Findings reference concrete spec paths, requirement ids, or graph objects where available.
|
|
30
|
-
- Follow-up work is expressed as recommended next workflows rather than hidden edits.
|