@agent-ix/quoin 0.3.5 → 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.
@@ -28,13 +28,13 @@ entries:
28
28
  ref: v0.2.0
29
29
 
30
30
  - name: spec-artifacts-process
31
- version: "0.2.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.2.0
37
+ ref: v0.3.0
38
38
 
39
39
  - name: spec-objects-business
40
40
  version: "0.3.0"
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agent-ix/quoin",
3
3
  "description": "Spec workflow and catalog CLI for Agent IX.",
4
- "version": "0.3.5",
4
+ "version": "0.3.7",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -2,6 +2,11 @@
2
2
 
3
3
  When an FR defines a domain object, set the `object:` frontmatter field and use the matching template.
4
4
 
5
+ > The `assets/...-template.md` names below identify each object type's template
6
+ > **within its catalog module** — they are not files shipped in this skill.
7
+ > Obtain the actual skeleton + schema with `quoin write --types <type>` (or
8
+ > inspect a type with `quoin catalog show <type>`).
9
+
5
10
  ## Business Objects (spec-objects-business)
6
11
 
7
12
  - `entity` / `aggregate_root` / `nested_entity`: Data entity, model, or aggregate → `assets/business/entity-template.md`
@@ -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. Manual Review:
40
+ 2. Base Review (always):
21
41
  - Read each artifact.
22
42
  - Verify against the **Checklist**.
23
43
  - Verify Test Coverage (6 Rules).
24
- - Run Analysis Skills:
25
- - `spec-failure-domain-analysis`
26
- - `spec-integrity-analysis`
27
- - `spec-dependency-analysis`
28
- - `spec-evidence-analysis`
29
- - `spec-risk-complexity-analysis`
30
- - `spec-scope-boundary-analysis`
31
- 3. Findings:
32
- - Document issues or gaps.
33
- - Assign action items.
34
- - Do not proceed to implementation until reviewed.
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 phases, gates, item schemas, recipes, and validation points.
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
- - Record evidence items before advancing analysis, review, or validation phases.
22
- - Use recipes for deterministic command chains, but preserve human gates for acceptance.
23
- - Prefer templates for stable artifact creation and generic file editing for broad semantic rewrites.
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: Records evidence items before validation.
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
- export { specInvariants as invariants } from "../../../dist/index.js";
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.1.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: evidence_recorded }
8
- - { name: report_rendered }
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: evidence_recorded
13
+ to: analyses_run
14
14
  invariants:
15
15
  - "interview.complete:request"
16
16
  defaultGate: auto
17
- - from: evidence_recorded
18
- to: report_rendered
17
+ - from: analyses_run
18
+ to: reviews_rendered
19
19
  invariants: []
20
20
  defaultGate: auto
21
- - from: report_rendered
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
- OperationReportSchema:
33
- required: [type, id, title, scope]
32
+ # One per analysis the agent ran + validated: a SpecReview doc on disk.
33
+ review_doc:
34
+ required: [analysis, path]
34
35
  properties:
35
- type: { type: string }
36
- id: { type: string }
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 inspect."
45
+ prompt: "Spec paths, requirement ids, or graph scope to review."
55
46
  type: text
56
47
  required: true
57
- - key: evidence
58
- prompt: "Evidence sources used for this operation."
59
- type: text
60
- required: true
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
- artifactTemplates:
66
- report:
67
- source: templates/report/default.md
68
- target: spec/reports/review/${items.operation_request.request.artifact_id}.md
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, render the operation report, validate it, then stop at acceptance.
59
+ description: Record inputs, then advance through analyses, rendering, validation, to acceptance.
74
60
  steps:
75
61
  - command: advance
76
- to: evidence_recorded
62
+ to: analyses_run
77
63
  - command: advance
78
- to: report_rendered
64
+ to: reviews_rendered
79
65
  - command: advance
80
66
  to: validated
81
67
  - command: advance
@@ -1,49 +1,102 @@
1
1
  ---
2
2
  name: specify
3
- description: Create or update spec files using quoin catalog authoring packs and Quire validation.
3
+ description: Create or update spec artifacts from a design or change request. Orchestrates authoring each requested requirement type (StR/US/FR/NFR/IT) as a discrete file using quoin catalog templates and Quire validation.
4
4
  ---
5
5
 
6
6
  # Specify
7
7
 
8
8
  Use this skill when turning an agreed design, feature, or change request into
9
- spec artifacts and supporting spec objects.
9
+ spec artifacts. `specify` decides **which artifacts the request needs**, authors
10
+ each one **as its own file** using the catalog templates, and validates.
10
11
 
11
- ## Process
12
+ ## Scope to the request
12
13
 
13
- 1. Identify the repository that owns the spec files.
14
- 2. Identify every artifact and object type that will be created or edited.
15
- 3. Run `quoin write <repo_dir> --types <type[,type...]>` once for the full set of types.
16
- 4. Use the returned skeletons, schemas, module roots, and examples as the authoring contract.
17
- 5. Author or edit the files directly in the target repo.
18
- 6. Run `quire validate <glob> [glob2 ...]` over the changed spec scope.
19
- 7. Fix validation errors before moving to review, matrix, or planning work.
14
+ Author **only the artifact types the request calls for** — nothing more.
20
15
 
21
- ## Type Selection
16
+ - "Add a user story for X" → one US.
17
+ - "Add the FR that implements US-003" → one FR (traced to US-003).
18
+ - "Add a user story and the requirement that implements it" → one US **and** one FR.
19
+ - "Edit FR-002 to …" → edit that one FR file in place.
20
+ - "Start a spec for service X" / "backport a spec from this code" → the full
21
+ chain (`spec.md` + US + FR + NFR, and IT where there are external integrations).
22
22
 
23
- Request all needed types together so the agent does not repeatedly fetch the
24
- same templates.
23
+ When unsure which types a request implies, decide from the request and state what
24
+ you are creating. A backport or new feature almost always needs **FR artifacts**,
25
+ not just a summary.
25
26
 
26
- Examples:
27
+ ## Requirements are files, not table rows
27
28
 
28
- ```bash
29
- quoin write . --types FR,domain,entity
30
- quoin write ../service --types StR,US,FR,NFR
31
- quoin write . --types process,configuration,value_object
32
- ```
29
+ Each requirement is a **discrete artifact file** with `type:` frontmatter. The
30
+ Requirements table inside `spec.md` (master-requirements) is an **index/summary**
31
+ — it never replaces the artifacts. Author every requested requirement as its own
32
+ file under the matching directory:
33
33
 
34
- Type lookup is catalog-driven and case-insensitive. Types may come from bundled
35
- `spec-artifacts-*`, bundled `spec-objects-*`, user-installed modules, or
36
- community modules.
34
+ | Type | `type:` | Location |
35
+ | ---- | ------- | ------------------------------ |
36
+ | StR | `StR` | `spec/stakeholder/StR-XXX-*.md`|
37
+ | US | `US` | `spec/usecase/US-XXX-*.md` |
38
+ | FR | `FR` | `spec/functional/FR-XXX-*.md` |
39
+ | NFR | `NFR` | `spec/non-functional/NFR-XXX-*.md` |
40
+ | IT | `IT` | `spec/integration/IT-XXX-*.md` |
37
41
 
38
- ## Authoring Rules
42
+ > If a request asks for functional requirements and you produced only table rows
43
+ > in `spec.md`, the request is **not done** — create the `FR-XXX.md` files.
44
+
45
+ ## Process
39
46
 
40
- - Let frontmatter identify exactly what each file is. The discriminator field is
41
- `type` (e.g. `type: FR`, `type: master-requirements`); it names the archetype the
42
- document conforms to.
47
+ Run only the steps the request needs; stop after IT.
48
+
49
+ 1. Identify the repository that owns the spec files, and which artifact types the
50
+ request implies (any subset of StR, US, FR, NFR, IT).
51
+ 2. Run `quoin write <repo_dir> --types <type[,type...]>` **once** for the full
52
+ set. Use the returned skeletons, schemas, module roots, and examples as the
53
+ authoring contract — the per-type rules live in the template, not your memory.
54
+ 3. Author each artifact as its own file (table above), in this logical order,
55
+ skipping any type not requested:
56
+ - `spec.md` — **REQUIRED when starting a new spec**: the
57
+ `type: master-requirements` root/index at `spec/spec.md`, authored from
58
+ `assets/spec-template.md` (or `assets/app-spec-template.md` for an
59
+ application). Then → StR → US →
60
+ **derive FR from US** (see [references/us-to-fr.md](references/us-to-fr.md))
61
+ → FR → NFR → IT (see [references/integration-tests.md](references/integration-tests.md)).
62
+ 4. Keep traceability in frontmatter `relationships:` (e.g. a US `traces_to` its
63
+ FRs; an FR/NFR/IT links back to the US/FR it serves).
64
+ 5. Run `quire validate <glob> [glob2 ...]` over the changed spec scope and fix
65
+ every error before continuing.
66
+ 6. **Stop at IT.** Then ask the user whether to build the test matrix
67
+ (`spec-matrix`) and run review (`spec-review`) — unless they already requested
68
+ them. Only run those on confirmation.
69
+
70
+ ## Functional requirements
71
+
72
+ FRs are normative (`SHALL` / `SHALL NOT`), atomic, and independently verifiable,
73
+ each with an Acceptance Criteria table (the `fr.md` skeleton enforces the shape).
74
+
75
+ - Derive FRs from the driving user story — see
76
+ [references/us-to-fr.md](references/us-to-fr.md).
77
+ - A behavioral FR has no `object:` field. A **domain-typed** FR carries
78
+ `object: <type>` (e.g. `entity`, `event`, `api_endpoint`, `process`,
79
+ `configuration`) and uses that type's structural template. Look up the
80
+ type→template map and relationship verbs in
81
+ `spec-object-review`'s `references/object-type-guide.md`, and inspect a type
82
+ with `quoin catalog show <type>`.
83
+
84
+ ## Application specs
85
+
86
+ When `component_type: application`, initialize `spec.md` from
87
+ `assets/app-spec-template.md`. Application specs own **only cross-service
88
+ concerns** — architecture rationale (ADRs), cross-service sequence diagrams,
89
+ system-level NFRs, the external consumer contract, scope boundaries, security
90
+ model. Per-service detail (endpoint contracts, DB schemas, per-service NFRs)
91
+ stays in the individual service specs. Otherwise use `assets/spec-template.md`.
92
+
93
+ ## Authoring rules
94
+
95
+ - Let frontmatter identify each file. The discriminator is `type` (e.g.
96
+ `type: FR`, `type: master-requirements`) — it names the archetype.
43
97
  - Use catalog skeletons and schemas rather than memory.
44
98
  - Keep workflow definitions out of artifact/object type vocabularies.
45
- - Validate every created or edited artifact with Quire.
46
- - Use `spec-review` after validation for quality, consistency, and completeness review.
99
+ - Validate every created or edited artifact with Quire before finishing.
47
100
 
48
101
  ## Reserved OKF Files
49
102
 
@@ -59,11 +112,11 @@ author them like any other type:
59
112
  ```text
60
113
  spec/
61
114
  ├── spec.md
62
- ├── stakeholder/
63
- ├── usecase/
64
- ├── functional/
65
- ├── non-functional/
66
- ├── integration/
115
+ ├── stakeholder/ # StR-XXX
116
+ ├── usecase/ # US-XXX
117
+ ├── functional/ # FR-XXX
118
+ ├── non-functional/ # NFR-XXX
119
+ ├── integration/ # IT-XXX
67
120
  ├── matrix/
68
121
  └── analysis/
69
122
  ```
@@ -0,0 +1,72 @@
1
+ # Authoring Integration Tests (IT)
2
+
3
+ Load this when a request involves integration tests — i.e. the system talks to
4
+ external services (HTTP APIs, event buses, databases, third-party/cloud APIs).
5
+ The per-section shape comes from the `IT` template (`quoin write --types IT`);
6
+ this file carries the *reasoning and reality rules* that the template can't
7
+ enforce.
8
+
9
+ ## Scope
10
+
11
+ HTTP client integrations, event bus connections (Kafka, RabbitMQ), database
12
+ connections (Postgres, Redis), and external APIs. One test case per file,
13
+ sequentially numbered (`IT-XXX`), saved to `spec/integration/IT-XXX-*.md`.
14
+
15
+ ## Reality rules — REAL by default
16
+
17
+ > Integration tests are **ALWAYS REAL** by default. Nothing is mocked unless the
18
+ > spec explicitly says so. An IT that only checks imports or constructs models
19
+ > without exercising real behavior is a **GAP**.
20
+
21
+ Every IT MUST include acceptance criteria from **both** categories:
22
+
23
+ - **Real Setup ACs** — the non-mocked environment is established: service running
24
+ and healthy (real health endpoint), real dependencies available (DB, bus,
25
+ external service), fixtures loaded into real stores, config applied through real
26
+ loading paths.
27
+ - **Real Output ACs** — real output from real services: HTTP responses
28
+ (status/headers/body), DB state changes (rows inserted/updated/deleted), events
29
+ published to and consumed from a real bus, file-system state, SSE/WebSocket
30
+ streams, LLM responses through real provider chains.
31
+
32
+ | Real (required) | Not real (GAP) |
33
+ | ------------------------------------------------- | ------------------------------ |
34
+ | POST to endpoint, assert response body | `assert MyModel is not None` |
35
+ | Query DB after a write, verify rows changed | `MyModel(field="value")` |
36
+ | Publish event, consume from real bus, verify load | `assert EventSchema is not None` |
37
+ | GET /health, verify HTTP 200 + status body | `assert app is not None` |
38
+
39
+ ### Mocking policy
40
+
41
+ - **Default: NO MOCKS.** ITs exercise real service boundaries.
42
+ - **Approved mock targets** only when the spec explicitly requires it: external
43
+ third-party APIs (payment, auth, cloud) via test doubles over real HTTP;
44
+ external services outside the test boundary via contract-faithful stubs.
45
+ - **Never mock**: HTTP transport, config loading, DB connections, file I/O,
46
+ session storage, event publishing, health endpoints, WebSocket/SSE connections.
47
+ - When a mock IS used, the IT must state WHY the real service can't be used, WHAT
48
+ boundary the mock replaces, and HOW the mock is verified faithful.
49
+
50
+ ## Process
51
+
52
+ 1. List the external dependencies from the codebase (the integration points).
53
+ 2. Take the next `IT-XXX`; get the contract with `quoin write --types IT`.
54
+ 3. Fill the template: Target Integration (service + protocol), Preconditions
55
+ (environment + data state), Test Data (`TD-XXX` fixtures with rationale),
56
+ Execution Plan (atomic steps, each with a timeout and `IT-XXX-SC-XX` success
57
+ criterion), Expected Outcome (success condition + failure modes).
58
+ 4. **Traceability is required**: every IT links to ≥1 FR/StR/NFR via frontmatter
59
+ `relationships:` (`type: verifies`). Cross-component references are fine
60
+ (e.g. `ix://org/other-service/FR-001`) per ISO 29148 bidirectional traceability.
61
+
62
+ ## Patterns by service type
63
+
64
+ - **API (FastAPI/REST)**: CRUD to real endpoints (verify codes/body/DB state);
65
+ invalid payloads → real 4xx; auth with/without creds → real 401/403.
66
+ - **Database**: real Alembic migrations → schema state; insert/query/update/delete
67
+ → row state; constraint violations → real DB errors.
68
+ - **Event-driven (FastStream)**: publish to a real topic, consume, verify payload;
69
+ produce an event, verify processing + side effects.
70
+ - **Worker**: submit a real job → completion state; slow job → timeout + cleanup.
71
+ - **Agent (LLM)**: deterministic scripted LLM via real API → verify tool calls;
72
+ real tool execution → file/process state; real SSE/WS → event sequence.
@@ -0,0 +1,40 @@
1
+ # Deriving Functional Requirements from a User Story
2
+
3
+ Load this when a request involves turning user stories into functional
4
+ requirements. It carries the *reasoning* for the derivation; the per-FR section
5
+ rules come from the `FR` template (`quoin write --types FR`).
6
+
7
+ ## Rules
8
+
9
+ - **Atomic**: decompose the story into specific, single-behavior FRs.
10
+ - **Normative**: FRs use `SHALL` / `SHALL NOT` (a US never does).
11
+ - **No copying**: translate intent into a technical specification — do not paste
12
+ the story text.
13
+ - **Verifiable**: every FR carries its own Acceptance Criteria table.
14
+
15
+ ## Process
16
+
17
+ 1. **Analyze** the `US-XXX`: list the system responsibilities it implies.
18
+ 2. **Decompose** into typed FRs. A behavioral FR (no `object:`) captures logic
19
+ and business rules. A domain-typed FR carries `object: <type>` and is purely
20
+ structural:
21
+ - `entity` — data model with typed fields
22
+ - `event` — a domain event emitted
23
+ - `api_endpoint` — a REST/HTTP endpoint
24
+ - `queue` — a message contract
25
+ - `process` — an end-to-end workflow
26
+ - `state_machine` — an entity lifecycle
27
+ - `configuration` — a configuration schema
28
+ - Full list + relationship verbs: `spec-object-review`'s
29
+ `references/object-type-guide.md`; inspect any type with
30
+ `quoin catalog show <type>`.
31
+ 3. **Author** each FR as its own file (`quoin write --types FR` for the contract),
32
+ and link it back to the story via frontmatter `relationships:`
33
+ (`type: implements`, target the `US-XXX`).
34
+ 4. **Specify** inputs/outputs (typed and validated), error handling (failure
35
+ modes), and constraints (technical limits, not options).
36
+ 5. **Separation of concerns**: keep behavioral triggers/validation in behavioral
37
+ FRs; domain-typed FR acceptance criteria test **structure** only (schema/field
38
+ presence), never behavior. Do not duplicate behavioral ACs into a domain FR.
39
+ 6. **Save** to `spec/functional/FR-XXX-description.md` (single repo) or
40
+ `specs/<category>/<component>/spec/functional/FR-XXX-description.md` (multi-repo).
@@ -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.