@agent-ix/quoin 0.10.0 → 0.12.0

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 (40) hide show
  1. package/default-modules.yaml +16 -16
  2. package/dist/{base-cpv9xSpO.js → base-DGA47VMM.js} +1 -1
  3. package/dist/cli.js +1 -1
  4. package/dist/commands/catalog/list.js +2 -2
  5. package/dist/commands/catalog/show.js +2 -2
  6. package/dist/commands/catalog/validate.js +2 -2
  7. package/dist/commands/config/doctor.js +1 -1
  8. package/dist/commands/config/edit.js +1 -1
  9. package/dist/commands/config/get.js +1 -1
  10. package/dist/commands/config/set.js +1 -1
  11. package/dist/commands/matrix.js +1 -1
  12. package/dist/commands/module/ensure-defaults.js +3 -3
  13. package/dist/commands/module/install.js +2 -2
  14. package/dist/commands/module/list.js +2 -2
  15. package/dist/commands/module/remove.js +2 -2
  16. package/dist/commands/review.js +1 -1
  17. package/dist/commands/to-plan.js +1 -1
  18. package/dist/commands/update.js +2 -2
  19. package/dist/commands/write.js +3 -3
  20. package/dist/{flow-command-DrC7aLJv.js → flow-command-CPS23AjI.js} +1 -1
  21. package/dist/index.js +6 -6
  22. package/dist/{modules-DelLm9BE.js → modules-CCvL41O_.js} +2 -2
  23. package/dist/{plugins-DQmOmTBH.js → plugins-ByvihMa0.js} +1 -1
  24. package/dist/{version-BWo5LBah.js → version-Be_NtSa4.js} +1 -1
  25. package/dist/{write-BZWI_GSS.js → write-xs9kemgB.js} +1 -1
  26. package/package.json +2 -1
  27. package/skills/spec-correctness/SKILL.md +98 -0
  28. package/skills/spec-correctness/assets/property-queue-template.md +78 -0
  29. package/skills/spec-correctness/assets/strategy-table.md +101 -0
  30. package/skills/spec-correctness/assets/templates/fast-check.ts.md +153 -0
  31. package/skills/spec-correctness/assets/templates/hypothesis.py.md +155 -0
  32. package/skills/spec-correctness/assets/templates/proptest.rs.md +144 -0
  33. package/skills/spec-correctness/references/step-0-scope-and-harness.md +94 -0
  34. package/skills/spec-correctness/references/step-1-census.md +53 -0
  35. package/skills/spec-correctness/references/step-2-clause-grounding.md +159 -0
  36. package/skills/spec-correctness/references/step-3-strategy-selection.md +83 -0
  37. package/skills/spec-correctness/references/step-4-generate-tests.md +99 -0
  38. package/skills/spec-correctness/references/step-5-second-pass.md +79 -0
  39. package/skills/spec-correctness/references/step-6-review-queue.md +64 -0
  40. package/skills/spec-correctness/references/step-7-report-and-handoff.md +63 -0
@@ -0,0 +1,153 @@
1
+ # TypeScript / fast-check templates
2
+
3
+ File: `tests/props/fr-NNN.prop.test.ts` (queued: `tests/props/_review/…`).
4
+ Inert marker: `it.skip` / `describe.skip`.
5
+ Runner: whichever the repo already uses — read `vitest.config.*`, `jest.config.*`, or
6
+ `package.json#scripts.test`. The imports below assume vitest; swap for `@jest/globals`
7
+ where the repo uses jest.
8
+
9
+ ## Anatomy
10
+
11
+ ```ts
12
+ // tests/props/fr-012.prop.test.ts
13
+ import fc from "fast-check";
14
+ import { describe, it, expect } from "vitest";
15
+ import { detectDuplicates, type Entry } from "../../src/catalog.js";
16
+
17
+ // grounded in step 2 from `## Inputs` + the signature at src/catalog.ts:88
18
+ const entryArb: fc.Arbitrary<Entry> = fc.record({
19
+ kind: fc.stringMatching(/^[a-z]{1,12}$/),
20
+ name: fc.stringMatching(/^[a-z]{1,12}$/),
21
+ });
22
+
23
+ /**
24
+ * Trace: FR-012-AC-1 — declaring modules are listed in sorted order.
25
+ * spec-correctness: row=FR-012-AC-1 property=ordering extraction=extractable origin=regex review=none
26
+ */
27
+ describe("FR-012-AC-1 duplicate modules are sorted", () => {
28
+ it("holds for any catalog", () => {
29
+ fc.assert(
30
+ fc.property(fc.array(entryArb, { maxLength: 32 }), (entries) => {
31
+ for (const d of detectDuplicates(entries).duplicates) {
32
+ expect(d.modules).toEqual([...d.modules].sort());
33
+ }
34
+ }),
35
+ );
36
+ });
37
+ });
38
+ ```
39
+
40
+ Both tag carriers: `Trace:` on its own JSDoc line, and `FR-012-AC-1` inside the `describe`
41
+ title.
42
+
43
+ ## Family bodies
44
+
45
+ ```ts
46
+ // round-trip
47
+ expect(parse(render(x))).toEqual(x);
48
+
49
+ // round-trip, lossy
50
+ expect(normalize(parse(render(x)))).toEqual(normalize(x));
51
+
52
+ // idempotence — seed with f's own outputs
53
+ const seeded = fc.oneof(rawConfigArb, rawConfigArb.map(normalize));
54
+ expect(normalize(normalize(x))).toEqual(normalize(x));
55
+
56
+ // invariant
57
+ expect(resolve(x).length).toBeLessThanOrEqual(MAX_MODULES);
58
+
59
+ // ordering, order-independence
60
+ expect(summarize(xs)).toEqual(summarize([...xs].reverse()));
61
+ ```
62
+
63
+ ## error-case — negative domain
64
+
65
+ ```ts
66
+ /**
67
+ * Trace: FR-005-AC-1 — an unknown command raises an error that names the usage.
68
+ * spec-correctness: row=FR-005-AC-1 property=error-case extraction=extractable origin=regex review=none
69
+ */
70
+ describe("FR-005-AC-1 unknown commands error", () => {
71
+ it("rejects any command outside the known set", () => {
72
+ fc.assert(
73
+ fc.property(fc.stringMatching(/^[a-z]{1,12}$/), (cmd) => {
74
+ fc.pre(!KNOWN.has(cmd));
75
+ expect(() => run([cmd])).toThrow(UnknownCommandError); // class, from src
76
+ expect(() => run([cmd])).toThrow(/Usage:/); // payload, from ## Outputs
77
+ }),
78
+ );
79
+ });
80
+ });
81
+ ```
82
+
83
+ ## lifecycle — fc.commands / modelRun
84
+
85
+ ```ts
86
+ /**
87
+ * Trace: FR-040-AC-2 — a session accepts exactly the ops its state allows.
88
+ * spec-correctness: row=FR-040-AC-2 property=lifecycle extraction=extractable origin=regex review=none
89
+ */
90
+ describe("FR-040-AC-2 session lifecycle", () => {
91
+ it("matches the model over any op sequence", () => {
92
+ fc.assert(
93
+ fc.property(fc.commands(allCommands, { maxCommands: 24 }), (cmds) =>
94
+ fc.modelRun(() => ({ model: newModel(), real: new Session() }), cmds),
95
+ ),
96
+ );
97
+ });
98
+ });
99
+ ```
100
+
101
+ Each command's `check(model)` is the precondition; its `run(model, real)` carries the
102
+ assertion. That split *is* the precondition/oracle split from step 2.
103
+
104
+ ## concurrency — deterministic scheduler
105
+
106
+ ```ts
107
+ /**
108
+ * Trace: FR-050-AC-1 — concurrent writers never lose an entry.
109
+ * spec-correctness: row=FR-050-AC-1 property=concurrency extraction=extractable origin=regex review=none
110
+ */
111
+ describe("FR-050-AC-1 concurrent writes", () => {
112
+ it("linearizes under any interleaving", async () => {
113
+ await fc.assert(
114
+ fc.asyncProperty(fc.scheduler(), async (s) => {
115
+ const store = new Store();
116
+ s.scheduleSequence([
117
+ { label: "a", builder: () => store.put("a", 1) },
118
+ { label: "b", builder: () => store.put("b", 2) },
119
+ ]);
120
+ await s.waitAll();
121
+ expect(store.size).toBe(2);
122
+ }),
123
+ );
124
+ });
125
+ });
126
+ ```
127
+
128
+ `fc.scheduler()` is deterministic and shrinkable — never use real timers or `Promise.all`
129
+ races for a concurrency property.
130
+
131
+ ## Queued form
132
+
133
+ ```ts
134
+ /**
135
+ * Trace: FR-018-AC-3 — a plugin source maps to exactly one resolved root.
136
+ * spec-correctness: row=FR-018-AC-3 property=invariant extraction=candidate origin=regex-candidate review=required
137
+ */
138
+ describe("FR-018-AC-3 source maps to one root", () => {
139
+ it.skip("spec-correctness review pending", () => { … });
140
+ });
141
+ ```
142
+
143
+ Acceptance turns `it.skip` into `it` and moves the file. The tag carriers are untouched.
144
+
145
+ ## Notes
146
+
147
+ - `fc.assert(fc.property(…))` synchronous, `await fc.assert(fc.asyncProperty(…))` async.
148
+ A forgotten `await` makes the test pass vacuously.
149
+ - Bound every `fc.array` with `maxLength`.
150
+ - `fc.pre(...)` inside the property, not around it.
151
+ - Return `void` or `boolean` from a property predicate — an assertion that throws is fine;
152
+ a returned truthy non-boolean is not.
153
+ - Reuse the repo's existing arbitraries and factories before writing new ones.
@@ -0,0 +1,155 @@
1
+ # Python / hypothesis templates
2
+
3
+ File: `tests/props/test_fr_NNN.py` (queued: `tests/props/_review/…`).
4
+ Inert marker: `@pytest.mark.skip(reason="spec-correctness review pending")`.
5
+
6
+ ## Anatomy
7
+
8
+ ```python
9
+ # tests/props/test_fr_012.py
10
+ from hypothesis import given, strategies as st
11
+
12
+ from quoin.catalog import Entry, detect_duplicates
13
+
14
+ # grounded in step 2 from `## Inputs` + the signature at src/quoin/catalog.py:88
15
+ entries = st.builds(
16
+ Entry,
17
+ kind=st.from_regex(r"\A[a-z]{1,12}\Z"),
18
+ name=st.from_regex(r"\A[a-z]{1,12}\Z"),
19
+ )
20
+
21
+
22
+ @given(catalog=st.lists(entries, max_size=32))
23
+ def test_fr_012_ac_1_duplicate_modules_sorted(catalog):
24
+ """Trace: FR-012-AC-1 — declaring modules are listed in sorted order.
25
+
26
+ spec-correctness: row=FR-012-AC-1 property=ordering extraction=extractable origin=regex review=none
27
+ """
28
+ for dup in detect_duplicates(catalog).duplicates:
29
+ assert dup.modules == sorted(dup.modules)
30
+ ```
31
+
32
+ Both tag carriers: `Trace:` on its own docstring line, and `fr_012_ac_1_` in the function
33
+ name.
34
+
35
+ ## Family bodies
36
+
37
+ ```python
38
+ # round-trip
39
+ assert parse(render(x)) == x
40
+
41
+ # round-trip, lossy
42
+ assert normalize(parse(render(x))) == normalize(x)
43
+
44
+ # idempotence — seed with f's own outputs
45
+ seeded = st.one_of(raw_configs, raw_configs.map(normalize))
46
+ assert normalize(normalize(x)) == normalize(x)
47
+
48
+ # invariant
49
+ assert len(resolve(x)) <= MAX_MODULES
50
+
51
+ # ordering, permutation preservation
52
+ assert Counter(reorder(xs)) == Counter(xs)
53
+ ```
54
+
55
+ ## error-case — negative domain
56
+
57
+ ```python
58
+ from hypothesis import assume
59
+ import pytest
60
+
61
+
62
+ @given(cmd=st.from_regex(r"\A[a-z]{1,12}\Z"))
63
+ def test_fr_005_ac_1_unknown_command_errors(cmd):
64
+ """Trace: FR-005-AC-1 — an unknown command raises an error that names the usage.
65
+
66
+ spec-correctness: row=FR-005-AC-1 property=error-case extraction=extractable origin=regex review=none
67
+ """
68
+ assume(cmd not in KNOWN)
69
+ with pytest.raises(UnknownCommandError, match="Usage:"):
70
+ run([cmd])
71
+ ```
72
+
73
+ `pytest.raises(Class, match=...)` carries both required assertions — the error class from
74
+ the code, the payload from `## Outputs` — in one line.
75
+
76
+ Prefer `st.sampled_from` over a broad regex plus `assume` when the negative domain is small;
77
+ too many `assume` rejections trip hypothesis's health checks.
78
+
79
+ ## lifecycle — RuleBasedStateMachine
80
+
81
+ ```python
82
+ from hypothesis.stateful import RuleBasedStateMachine, invariant, precondition, rule
83
+
84
+
85
+ class SessionMachine(RuleBasedStateMachine):
86
+ """Trace: FR-040-AC-2 — a session accepts exactly the ops its state allows.
87
+
88
+ spec-correctness: row=FR-040-AC-2 property=lifecycle extraction=extractable origin=regex review=none
89
+ """
90
+
91
+ def __init__(self):
92
+ super().__init__()
93
+ self.sut = Session()
94
+ self.model = []
95
+
96
+ @rule()
97
+ def open(self):
98
+ self.sut.open()
99
+
100
+ @rule(data=st.text(max_size=64))
101
+ @precondition(lambda self: self.sut.is_open)
102
+ def write(self, data):
103
+ self.sut.write(data)
104
+ self.model.append(data)
105
+
106
+ @invariant()
107
+ def buffer_matches_model(self):
108
+ assert self.sut.buffer == "".join(self.model)
109
+
110
+
111
+ TestSessionLifecycle = SessionMachine.TestCase
112
+ ```
113
+
114
+ `@precondition` is the step-2 precondition; `@invariant` is the step-2 oracle.
115
+
116
+ ## concurrency — always queued
117
+
118
+ hypothesis ships no interleaving scheduler, so a Python concurrency criterion is never
119
+ emitted unattended. Emit a `RuleBasedStateMachine` over the async model, queued:
120
+
121
+ ```python
122
+ @pytest.mark.skip(reason="spec-correctness review pending")
123
+ class TestConcurrentWrites(RuleBasedStateMachine):
124
+ """Trace: FR-050-AC-1 — concurrent writers never lose an entry.
125
+
126
+ spec-correctness: row=FR-050-AC-1 property=concurrency extraction=not-extractable origin=llm-second-pass review=required confidence=low
127
+ """
128
+ ```
129
+
130
+ Say in the queue row that the interleaving is not exhaustively explored — that is the
131
+ reason it needs a person.
132
+
133
+ ## Queued form
134
+
135
+ ```python
136
+ @pytest.mark.skip(reason="spec-correctness review pending")
137
+ @given(src=plugin_sources)
138
+ def test_fr_018_ac_3_source_maps_to_one_root(src):
139
+ """Trace: FR-018-AC-3 — a plugin source maps to exactly one resolved root.
140
+
141
+ spec-correctness: row=FR-018-AC-3 property=invariant extraction=candidate origin=regex-candidate review=required
142
+ """
143
+ ```
144
+
145
+ Acceptance deletes the `@pytest.mark.skip` line and moves the file. The tag carriers do not
146
+ change.
147
+
148
+ ## Notes
149
+
150
+ - `@given` outermost, `@pytest.mark.*` above it; hypothesis and pytest fixtures do not mix
151
+ freely — pass state through the strategy, not through a function-scoped fixture.
152
+ - Bound every `st.lists` with `max_size`, every `st.text` with `max_size`.
153
+ - Never `@seed(...)` a generated test, and never `@settings(derandomize=True)` — both hide
154
+ the failures the property exists to find.
155
+ - Raise `max_examples` only with a reason recorded in the queue.
@@ -0,0 +1,144 @@
1
+ # Rust / proptest templates
2
+
3
+ File: `tests/props_fr_NNN.rs` (queued: `tests/props_review_fr_NNN.rs`).
4
+ Inert marker: `#[ignore = "spec-correctness review pending"]`.
5
+
6
+ Paths are **flat**: cargo auto-discovers integration tests only at `tests/*.rs`. A file
7
+ under `tests/props/` compiles as a helper module and never runs. See step 4.
8
+
9
+ ## Anatomy
10
+
11
+ ```rust
12
+ // tests/props_fr_012.rs
13
+ use proptest::prelude::*;
14
+ use quoin::catalog::{detect_duplicates, Entry};
15
+
16
+ fn entry() -> impl Strategy<Value = Entry> {
17
+ // grounded in step 2 from `## Inputs` + the signature at src/catalog.rs:88
18
+ ("[a-z]{1,12}", "[a-z]{1,12}").prop_map(|(kind, name)| Entry::new(kind, name))
19
+ }
20
+
21
+ proptest! {
22
+ /// Trace: FR-012-AC-1 — declaring modules are listed in sorted order.
23
+ /// spec-correctness: row=FR-012-AC-1 property=ordering extraction=extractable origin=regex review=none
24
+ #[test]
25
+ fn fr_012_ac_1_duplicate_modules_sorted(entries in prop::collection::vec(entry(), 0..32)) {
26
+ for dup in detect_duplicates(&entries).duplicates {
27
+ let mut sorted = dup.modules.clone();
28
+ sorted.sort();
29
+ prop_assert_eq!(dup.modules, sorted);
30
+ }
31
+ }
32
+ }
33
+ ```
34
+
35
+ Both tag carriers are present: `Trace:` on its own doc-comment line, and `fr_012_ac_1_` in
36
+ the function name.
37
+
38
+ ## Family bodies
39
+
40
+ Same `proptest! { #[test] fn … }` wrapper; only the assertion changes.
41
+
42
+ ```rust
43
+ // round-trip
44
+ prop_assert_eq!(parse(&render(&x))?, x);
45
+
46
+ // round-trip, lossy (cite the FR line stating the loss)
47
+ prop_assert_eq!(normalize(&parse(&render(&x))?), normalize(&x));
48
+
49
+ // idempotence — seed with f's own outputs
50
+ fn seeded() -> impl Strategy<Value = Config> {
51
+ prop_oneof![raw_config(), raw_config().prop_map(|c| normalize(&c))]
52
+ }
53
+ prop_assert_eq!(normalize(&normalize(&x)), normalize(&x));
54
+
55
+ // invariant
56
+ prop_assert!(resolve(&x).len() <= MAX_MODULES);
57
+ ```
58
+
59
+ ## error-case — negative domain
60
+
61
+ ```rust
62
+ proptest! {
63
+ /// Trace: FR-005-AC-1 — an unknown command raises an error that names the usage.
64
+ /// spec-correctness: row=FR-005-AC-1 property=error-case extraction=extractable origin=regex review=none
65
+ #[test]
66
+ fn fr_005_ac_1_unknown_command_errors(
67
+ cmd in "[a-z]{1,12}".prop_filter("must be unknown", |c| !KNOWN.contains(&c.as_str()))
68
+ ) {
69
+ let err = run(&[cmd.as_str()]).unwrap_err();
70
+ prop_assert!(matches!(err, Error::UnknownCommand(_))); // class, from the error enum
71
+ prop_assert!(err.to_string().contains("Usage:")); // payload, from ## Outputs
72
+ }
73
+ }
74
+ ```
75
+
76
+ ## lifecycle — model vs SUT
77
+
78
+ ```rust
79
+ proptest! {
80
+ /// Trace: FR-040-AC-2 — a session accepts exactly the ops its state allows.
81
+ /// spec-correctness: row=FR-040-AC-2 property=lifecycle extraction=extractable origin=regex review=none
82
+ #[test]
83
+ fn fr_040_ac_2_session_lifecycle(ops in prop::collection::vec(any_op(), 1..24)) {
84
+ let (mut model, mut sut) = (Model::default(), Session::new());
85
+ for op in ops {
86
+ let legal = model.allows(&op);
87
+ prop_assert_eq!(sut.apply(&op).is_ok(), legal);
88
+ if legal { model.apply(&op); }
89
+ prop_assert!(sut.invariant_holds());
90
+ }
91
+ prop_assert_eq!(sut.state(), model.state());
92
+ }
93
+ }
94
+ ```
95
+
96
+ ## concurrency — loom
97
+
98
+ Not a `proptest!` block; `loom` enumerates interleavings itself.
99
+
100
+ ```rust
101
+ /// Trace: FR-050-AC-1 — concurrent writers never lose an entry.
102
+ /// spec-correctness: row=FR-050-AC-1 property=concurrency extraction=extractable origin=regex review=none
103
+ #[test]
104
+ fn fr_050_ac_1_concurrent_writes_linearizable() {
105
+ loom::model(|| {
106
+ let store = loom::sync::Arc::new(Store::new());
107
+ let handles: Vec<_> = (0..2)
108
+ .map(|i| { let s = store.clone(); loom::thread::spawn(move || s.put(i, i)) })
109
+ .collect();
110
+ for h in handles { h.join().unwrap(); }
111
+ assert_eq!(store.len(), 2);
112
+ });
113
+ }
114
+ ```
115
+
116
+ Keep the loom model tiny — two threads, two ops. Interleavings explode.
117
+
118
+ ## Queued form
119
+
120
+ ```rust
121
+ proptest! {
122
+ /// Trace: FR-018-AC-3 — a plugin source maps to exactly one resolved root.
123
+ /// spec-correctness: row=FR-018-AC-3 property=invariant extraction=candidate origin=regex-candidate review=required
124
+ #[test]
125
+ #[ignore = "spec-correctness review pending"]
126
+ fn fr_018_ac_3_source_maps_to_one_root(src in plugin_source()) { … }
127
+ }
128
+ ```
129
+
130
+ Acceptance deletes the `#[ignore]` line and moves the file. The two tag carriers do not
131
+ change.
132
+
133
+ ## Notes
134
+
135
+ - **Import by the `[lib] name`, not the package name.** They differ often —
136
+ `package.name = "quire-rs"` but `lib.name = "quire_rs"`, so an integration test writes
137
+ `use quire_rs::…`. Read `[lib] name` in `Cargo.toml`; fall back to the package name with
138
+ `-` replaced by `_` only when no `[lib]` block declares one.
139
+ - `prop_assert*` inside `proptest!`, plain `assert*` inside `loom::model`.
140
+ - Bound every `prop::collection::vec` — `0..32` unless the FR states a bound.
141
+ - Prefer building a negative domain directly over `prop_filter` when the filter rejects
142
+ most values; proptest gives up after too many rejections.
143
+ - Do not set `ProptestConfig { cases, .. }` above the default without recording why in the
144
+ queue.
@@ -0,0 +1,94 @@
1
+ # Step 0: Scope and Harness
2
+
3
+ **Goal**: know what you are classifying, what harness you are writing into, and what
4
+ tracking-tag form the repo already uses.
5
+
6
+ ## 1. Resolve scope
7
+
8
+ Repo root = the directory holding the spec tree. Default glob `spec/**/*.md`; a multi-repo
9
+ layout uses `specs/<category>/<component>/spec/**/*.md`.
10
+
11
+ ## 2. Run the classifier
12
+
13
+ ```
14
+ quire properties --scope <repo> --json 'spec/**/*.md'
15
+ ```
16
+
17
+ Requires quire-cli ≥ 0.12.0 (`quire --version`). Output shape:
18
+
19
+ ```json
20
+ {"documents": [{
21
+ "document": "<abs path>",
22
+ "archetype": "FR",
23
+ "criteria": [{
24
+ "row_id": "FR-027-AC-1",
25
+ "statement": "A stored organization is used ahead of the `origin` remote…",
26
+ "line": 74,
27
+ "shape": "assertion",
28
+ "property": "universal",
29
+ "extractable": true,
30
+ "extraction": "extractable",
31
+ "domain": null, "precondition": null, "oracle": null,
32
+ "signals": ["universal:determiner"]
33
+ }]
34
+ }]}
35
+ ```
36
+
37
+ Field notes that matter:
38
+
39
+ - `row_id` — the only identifier shared with the matrix and with `gap-analysis`. Never
40
+ synthesize one, never alter one. A record with `row_id: null` cannot be tagged, so it
41
+ goes straight to the queue with reason `no-row-id`.
42
+ - `line` is 1-based and **file**-relative. Span `start`/`end` are **statement**-relative
43
+ byte offsets into `statement`. Do not mix them.
44
+ - Spans are usually `null` (they reach ~4% of the ecosystem corpus). Their absence says
45
+ nothing about the criterion; step 2 grounds the clauses regardless.
46
+ - `signals` is an audit trail, useful for diagnosis. `span:refused-weak-boundary` means the
47
+ engine declined to guess a boundary — read it as "the oracle must come from the code."
48
+
49
+ Add `--pretty` while developing. Stderr carries module diagnostics (`DuplicateArchetype`
50
+ etc.); they are noise for this skill, not findings.
51
+
52
+ ## 3. Detect the harness
53
+
54
+ Probe the repo root, in this order. Record harness, generator library presence, test dir,
55
+ and runner.
56
+
57
+ | Harness | Manifest | Generator library | Test path |
58
+ | --- | --- | --- | --- |
59
+ | Rust / proptest | `Cargo.toml` | `proptest`, `proptest-state-machine`, `loom`, `arbitrary` in `[dev-dependencies]` | `tests/props_fr_NNN.rs` (flat — cargo discovers only `tests/*.rs`) |
60
+ | TypeScript / fast-check | `package.json` | `fast-check` in `devDependencies`; runner from `vitest.config.*`, `jest.config.*`, or `package.json#scripts.test` | `tests/props/fr-NNN.prop.test.ts` |
61
+ | Python / hypothesis | `pyproject.toml`, `setup.cfg`, `requirements*.txt` | `hypothesis`; runner from `pytest.ini` / `tox.ini` / `conftest.py` | `tests/props/test_fr_NNN.py` |
62
+
63
+ Rules:
64
+
65
+ - **Manifest present, generator library absent** — install nothing, and **write no test
66
+ files**. A file that imports a missing generator library breaks the suite even when every
67
+ test in it is skipped, because the import is evaluated at collection time. Record the
68
+ proposals as fenced code blocks in the queue instead, and report one line:
69
+ `harness <lib> not installed — add <lib> to <dev-deps>, then re-run to emit these`.
70
+ Adding a dependency is the user's call, not this skill's.
71
+ - **Polyglot repo** — resolve per-FR from the AC table's `Verification` column, which names
72
+ the test file (`Test (org.test.ts)` → TypeScript). If that column is absent, use the tree
73
+ holding the symbol step 2 grounded. Never pick one harness repo-wide by guessing.
74
+ - **No harness at all** — stop after steps 1 and 2. Emit the grounded strategies as prose
75
+ in the queue file. Write no test files.
76
+
77
+ ## 4. Detect the existing tag style
78
+
79
+ Grep the existing test tree for the four forms `gap-analysis` accepts
80
+ (`skills/gap-analysis/references/step-3-matrix-verification.md`):
81
+
82
+ ```
83
+ Trace: FR-
84
+ FR-[0-9]{3}-AC-
85
+ TC-[0-9]{3}
86
+ Tests for FR-
87
+ ```
88
+
89
+ Mimic the dominant form. The tags in step 4 are additive to it, never a replacement — if
90
+ this repo writes `// FR-025-AC-7:` line comments, keep writing those too.
91
+
92
+ ## Output of this step
93
+
94
+ `{repo, glob, records[], harness, generator_lib_present, test_dir, runner, tag_style}`.
@@ -0,0 +1,53 @@
1
+ # Step 1: Census
2
+
3
+ **Goal**: state what the classifier found, as counts, so the rest of the run has a
4
+ denominator. Nothing in this step is a judgement.
5
+
6
+ ## Bucket
7
+
8
+ Cross-tabulate the records two ways:
9
+
10
+ - `property` × `extraction` — this drives routing and volume.
11
+ - `archetype` × `extraction` — this tells you where the properties live (FR? StR? NFR?).
12
+
13
+ Report the totals plainly:
14
+
15
+ ```
16
+ Criteria: 118
17
+ extraction extractable 51 · candidate 0 · not-extractable 67
18
+ property universal 43 · example 59 · error-case 9 · unclassified 5 · ordering 2
19
+ archetype FR 84 · NFR 21 · StR 13
20
+ spans present domain 4 · precondition 2 · oracle 5
21
+ ```
22
+
23
+ ## What this step must never emit
24
+
25
+ - A threshold, a target, a percentage framed as a score, or a grade of any kind.
26
+ - A pass/fail, a verdict, or a severity. The classification carries no severity key and no
27
+ promotion path by design (quire-rs FR-052-CON-1).
28
+ - A suggestion to reword, split, or "improve" any criterion. Not as a recommendation, not
29
+ as a note, not as a parenthetical. If a criterion is a concrete example, the correct
30
+ response is an example-based test, not an edit to the spec.
31
+ - A comparison of this repo against another repo's ratio.
32
+
33
+ Phrase counts as facts: "59 criteria are concrete examples" — not "only 43% are
34
+ extractable" and never "consider rewriting the 59 example criteria as properties."
35
+
36
+ ## What is worth flagging (as information)
37
+
38
+ - Records with `row_id: null` — they cannot be tagged, so they cannot be reconciled. Route
39
+ to the queue with reason `no-row-id`.
40
+ - Documents that produced zero criteria — usually the archetype binds no `ac` grammar
41
+ (US and IT are unbound), which is expected, not a gap.
42
+ - A `candidate` count above zero — rare (0.4% of the corpus). Worth naming because every
43
+ one of them is review-gated by construction.
44
+
45
+ ## Archetype note
46
+
47
+ Do **not** down-weight StR. The measured ranking is StR 29.1% > NFR 28.9% > FR 19.2%
48
+ (quire-rs CR-029, which falsified the earlier CR-020 prediction that StR would score low).
49
+ Stakeholder criteria produce good properties.
50
+
51
+ ## Output of this step
52
+
53
+ The census tables, plus the working set for step 2: every record with a `row_id`.