@agent-ix/quoin 0.12.0 → 0.12.2

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 (48) hide show
  1. package/dist/{base-DGA47VMM.js → base-DD0ONCEf.js} +1 -1
  2. package/dist/cli.d.ts +15 -0
  3. package/dist/cli.d.ts.map +1 -1
  4. package/dist/cli.js +11 -7
  5. package/dist/commands/catalog/list.js +2 -2
  6. package/dist/commands/catalog/show.js +2 -2
  7. package/dist/commands/catalog/validate.js +2 -2
  8. package/dist/commands/config/doctor.js +1 -1
  9. package/dist/commands/config/edit.js +1 -1
  10. package/dist/commands/config/get.js +1 -1
  11. package/dist/commands/config/set.js +1 -1
  12. package/dist/commands/matrix.js +1 -1
  13. package/dist/commands/module/ensure-defaults.js +3 -3
  14. package/dist/commands/module/install.js +2 -2
  15. package/dist/commands/module/list.js +2 -2
  16. package/dist/commands/module/remove.js +2 -2
  17. package/dist/commands/review.js +1 -1
  18. package/dist/commands/to-plan.js +1 -1
  19. package/dist/commands/update.js +2 -2
  20. package/dist/commands/write.js +3 -3
  21. package/dist/{flow-command-CPS23AjI.js → flow-command-DK5LDrtg.js} +1 -1
  22. package/dist/hooks/command-not-found.d.ts +23 -0
  23. package/dist/hooks/command-not-found.d.ts.map +1 -0
  24. package/dist/hooks/command-not-found.js +8 -0
  25. package/dist/index.js +6 -6
  26. package/dist/{modules-CCvL41O_.js → modules-_4_rnXpw.js} +2 -2
  27. package/dist/{plugins-ByvihMa0.js → plugins-BO1uLsfi.js} +1 -1
  28. package/dist/{version-Be_NtSa4.js → version-DIJF4enj.js} +1 -1
  29. package/dist/{write-xs9kemgB.js → write-D462q_kk.js} +1 -1
  30. package/package.json +5 -2
  31. package/skills/gap-analysis/SKILL.md +5 -3
  32. package/skills/gap-analysis/references/step-3-matrix-verification.md +94 -24
  33. package/skills/gap-analysis/references/step-6-specreview-artifact.md +6 -1
  34. package/skills/spec-correctness/SKILL.md +11 -13
  35. package/skills/spec-correctness/assets/strategy-table.md +3 -3
  36. package/skills/spec-correctness/assets/templates/fast-check.ts.md +41 -25
  37. package/skills/spec-correctness/assets/templates/hypothesis.py.md +16 -15
  38. package/skills/spec-correctness/assets/templates/proptest.rs.md +12 -9
  39. package/skills/spec-correctness/references/step-0-scope-and-harness.md +6 -6
  40. package/skills/spec-correctness/references/step-1-census.md +1 -1
  41. package/skills/spec-correctness/references/step-2-clause-grounding.md +2 -2
  42. package/skills/spec-correctness/references/step-3-strategy-selection.md +13 -11
  43. package/skills/spec-correctness/references/step-4-generate-tests.md +43 -25
  44. package/skills/spec-correctness/references/step-5-second-pass.md +11 -9
  45. package/skills/spec-correctness/references/step-6-review-artifact.md +121 -0
  46. package/skills/spec-correctness/references/step-7-report-and-handoff.md +38 -17
  47. package/skills/spec-correctness/assets/property-queue-template.md +0 -78
  48. package/skills/spec-correctness/references/step-6-review-queue.md +0 -64
@@ -1,4 +1,4 @@
1
- import { t as e } from "./version-Be_NtSa4.js";
1
+ import { t as e } from "./version-DIJF4enj.js";
2
2
  import { BaseCommand as t, maybeOfferUpdate as n } from "@agent-ix/ix-cli-core";
3
3
  import { existsSync as r, readFileSync as i, readdirSync as a, statSync as o } from "node:fs";
4
4
  import { basename as s, join as c, resolve as l } from "node:path";
package/dist/cli.d.ts CHANGED
@@ -1,5 +1,20 @@
1
1
  import { RunnerLoadOptions } from '@agent-ix/ix-cli-core';
2
2
  export { packageVersion, resolveVersion } from './version.js';
3
+ /**
4
+ * Root usage: the bin name plus the top-level command ids oclif discovered.
5
+ *
6
+ * Built from the resolved config rather than a hand-maintained string, so a
7
+ * command added to `dist/commands` (or contributed by a core plugin) appears
8
+ * here without a second edit — the failure mode FR-003's delegation to oclif
9
+ * exists to avoid.
10
+ */
11
+ export declare function rootUsage(config: {
12
+ bin: string;
13
+ commands: ReadonlyArray<{
14
+ id: string;
15
+ hidden?: boolean;
16
+ }>;
17
+ }): string;
3
18
  export declare function isVersionRequest(argv: readonly string[]): boolean;
4
19
  /**
5
20
  * quoin entry point.
package/dist/cli.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAIpE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAS9D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAMf"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAIpE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC3D,GAAG,MAAM,CAST;AASD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAMf"}
package/dist/cli.js CHANGED
@@ -1,20 +1,24 @@
1
- import { n as e, t } from "./version-Be_NtSa4.js";
1
+ import { n as e, t } from "./version-DIJF4enj.js";
2
2
  import { run as n } from "@agent-ix/ix-cli-core";
3
3
  //#region src/cli.ts
4
- var r = new Set([
4
+ function r(e) {
5
+ let t = [...new Set(e.commands.filter((e) => !e.hidden).map((e) => e.id.split(":")[0]))].sort();
6
+ return `Usage: ${e.bin} <command> [options]\n\nCommands: ${t.join(", ")}\n\nRun \`${e.bin} <command> --help\` for details.`;
7
+ }
8
+ var i = new Set([
5
9
  "--version",
6
10
  "-v",
7
11
  "version"
8
12
  ]);
9
- function i(e) {
10
- return e.length > 0 && r.has(e[0]);
13
+ function a(e) {
14
+ return e.length > 0 && i.has(e[0]);
11
15
  }
12
- async function a(e, r) {
13
- if (i(e)) {
16
+ async function o(e, r) {
17
+ if (a(e)) {
14
18
  console.log(t());
15
19
  return;
16
20
  }
17
21
  await n(e, r);
18
22
  }
19
23
  //#endregion
20
- export { i as isVersionRequest, a as main, t as packageVersion, e as resolveVersion };
24
+ export { a as isVersionRequest, o as main, t as packageVersion, e as resolveVersion, r as rootUsage };
@@ -1,5 +1,5 @@
1
- import { o as e, t } from "../../base-DGA47VMM.js";
2
- import { n } from "../../modules-CCvL41O_.js";
1
+ import { o as e, t } from "../../base-DD0ONCEf.js";
2
+ import { n } from "../../modules-_4_rnXpw.js";
3
3
  import { Flags as r } from "@oclif/core";
4
4
  //#region src/commands/catalog/list.ts
5
5
  var i = class i extends t {
@@ -1,5 +1,5 @@
1
- import { i as e, o as t, t as n } from "../../base-DGA47VMM.js";
2
- import { n as r } from "../../modules-CCvL41O_.js";
1
+ import { i as e, o as t, t as n } from "../../base-DD0ONCEf.js";
2
+ import { n as r } from "../../modules-_4_rnXpw.js";
3
3
  import { Args as i, Flags as a } from "@oclif/core";
4
4
  //#region src/commands/catalog/show.ts
5
5
  var o = class o extends n {
@@ -1,5 +1,5 @@
1
- import { o as e, t } from "../../base-DGA47VMM.js";
2
- import { n } from "../../modules-CCvL41O_.js";
1
+ import { o as e, t } from "../../base-DD0ONCEf.js";
2
+ import { n } from "../../modules-_4_rnXpw.js";
3
3
  import { Flags as r } from "@oclif/core";
4
4
  //#region src/commands/catalog/validate.ts
5
5
  var i = class i extends t {
@@ -1,4 +1,4 @@
1
- import { t as e } from "../../base-DGA47VMM.js";
1
+ import { t as e } from "../../base-DD0ONCEf.js";
2
2
  import { a as t } from "../../config-schema-Dp-vlxuR.js";
3
3
  import { runConfigDoctor as n } from "@agent-ix/ix-cli-core";
4
4
  //#region src/commands/config/doctor.ts
@@ -1,4 +1,4 @@
1
- import { t as e } from "../../base-DGA47VMM.js";
1
+ import { t as e } from "../../base-DD0ONCEf.js";
2
2
  import { a as t, n } from "../../config-schema-Dp-vlxuR.js";
3
3
  import { runConfigEdit as r } from "@agent-ix/ix-cli-core";
4
4
  //#region src/commands/config/edit.ts
@@ -1,4 +1,4 @@
1
- import { t as e } from "../../base-DGA47VMM.js";
1
+ import { t as e } from "../../base-DD0ONCEf.js";
2
2
  import { a as t, n } from "../../config-schema-Dp-vlxuR.js";
3
3
  import { runConfigGet as r } from "@agent-ix/ix-cli-core";
4
4
  import { Args as i } from "@oclif/core";
@@ -1,4 +1,4 @@
1
- import { t as e } from "../../base-DGA47VMM.js";
1
+ import { t as e } from "../../base-DD0ONCEf.js";
2
2
  import { a as t, n } from "../../config-schema-Dp-vlxuR.js";
3
3
  import { runConfigSet as r } from "@agent-ix/ix-cli-core";
4
4
  import { Args as i } from "@oclif/core";
@@ -1,4 +1,4 @@
1
- import { t as e } from "../flow-command-CPS23AjI.js";
1
+ import { t as e } from "../flow-command-DK5LDrtg.js";
2
2
  //#region src/commands/matrix.ts
3
3
  var t = class t extends e {
4
4
  static summary = "Build or update a requirements test matrix.";
@@ -1,6 +1,6 @@
1
- import { t as e } from "../../base-DGA47VMM.js";
2
- import { r as t } from "../../plugins-ByvihMa0.js";
3
- import { n } from "../../modules-CCvL41O_.js";
1
+ import { t as e } from "../../base-DD0ONCEf.js";
2
+ import { r as t } from "../../plugins-BO1uLsfi.js";
3
+ import { n } from "../../modules-_4_rnXpw.js";
4
4
  //#region src/commands/module/ensure-defaults.ts
5
5
  var r = class r extends e {
6
6
  static summary = "Idempotently install the default spec module set.";
@@ -1,5 +1,5 @@
1
- import { t as e } from "../../base-DGA47VMM.js";
2
- import { n as t } from "../../plugins-ByvihMa0.js";
1
+ import { t as e } from "../../base-DD0ONCEf.js";
2
+ import { n as t } from "../../plugins-BO1uLsfi.js";
3
3
  import { Args as n } from "@oclif/core";
4
4
  //#region src/commands/module/install.ts
5
5
  var r = class r extends e {
@@ -1,5 +1,5 @@
1
- import { t as e } from "../../base-DGA47VMM.js";
2
- import { r as t } from "../../plugins-ByvihMa0.js";
1
+ import { t as e } from "../../base-DD0ONCEf.js";
2
+ import { r as t } from "../../plugins-BO1uLsfi.js";
3
3
  //#region src/commands/module/list.ts
4
4
  var n = class n extends e {
5
5
  static summary = "List installed spec modules.";
@@ -1,5 +1,5 @@
1
- import { t as e } from "../../base-DGA47VMM.js";
2
- import { a as t } from "../../plugins-ByvihMa0.js";
1
+ import { t as e } from "../../base-DD0ONCEf.js";
2
+ import { a as t } from "../../plugins-BO1uLsfi.js";
3
3
  import { Args as n } from "@oclif/core";
4
4
  //#region src/commands/module/remove.ts
5
5
  var r = class r extends e {
@@ -1,4 +1,4 @@
1
- import { t as e } from "../flow-command-CPS23AjI.js";
1
+ import { t as e } from "../flow-command-DK5LDrtg.js";
2
2
  //#region src/commands/review.ts
3
3
  var t = class t extends e {
4
4
  static summary = "Run a composite spec review workflow.";
@@ -1,4 +1,4 @@
1
- import { t as e } from "../flow-command-CPS23AjI.js";
1
+ import { t as e } from "../flow-command-DK5LDrtg.js";
2
2
  //#region src/commands/to-plan.ts
3
3
  var t = class t extends e {
4
4
  static summary = "Convert accepted requirements into an implementation plan.";
@@ -1,5 +1,5 @@
1
- import { t as e } from "../version-Be_NtSa4.js";
2
- import { t } from "../base-DGA47VMM.js";
1
+ import { t as e } from "../version-DIJF4enj.js";
2
+ import { t } from "../base-DD0ONCEf.js";
3
3
  import { runSelfUpdate as n } from "@agent-ix/ix-cli-core";
4
4
  import { Flags as r } from "@oclif/core";
5
5
  //#region src/commands/update.ts
@@ -1,6 +1,6 @@
1
- import { o as e, t } from "../base-DGA47VMM.js";
2
- import { n } from "../modules-CCvL41O_.js";
3
- import { n as r, r as i, t as a } from "../write-xs9kemgB.js";
1
+ import { o as e, t } from "../base-DD0ONCEf.js";
2
+ import { n } from "../modules-_4_rnXpw.js";
3
+ import { n as r, r as i, t as a } from "../write-D462q_kk.js";
4
4
  import { Args as o, Flags as s } from "@oclif/core";
5
5
  //#region src/commands/write.ts
6
6
  var c = class c extends t {
@@ -1,4 +1,4 @@
1
- import { a as e, t } from "./base-DGA47VMM.js";
1
+ import { a as e, t } from "./base-DD0ONCEf.js";
2
2
  import { existsSync as n } from "node:fs";
3
3
  import { dirname as r, join as i, resolve as a } from "node:path";
4
4
  import { fileURLToPath as o } from "node:url";
@@ -0,0 +1,23 @@
1
+ import { Hook } from '@oclif/core';
2
+ /**
3
+ * `command_not_found` hook — attach the root usage to an unknown command
4
+ * (FR-005-AC-1).
5
+ *
6
+ * The hand-rolled dispatcher FR-026 replaced printed usage on an unknown
7
+ * command. The oclif runner reports only `command <x> not found`, which names
8
+ * the mistake but not the remedy, leaving NFR-003 unmet on the one path a
9
+ * mistyping user is guaranteed to hit.
10
+ *
11
+ * This is oclif's own extension point for that: `Config.runCommand` invokes it
12
+ * when no command matches, and rethrows a hook failure in place of its default
13
+ * error. So the message is fixed where oclif expects it to be fixed — no error
14
+ * sniffing (the thrown `CLIError` carries no stable discriminator), and no
15
+ * bypassing `execute`, whose `flush()` the shipped bin needs so piped output is
16
+ * not truncated on exit.
17
+ *
18
+ * It fires on the library path too: `run(argv, config)` reaches the same
19
+ * `Config.runCommand`.
20
+ */
21
+ declare const hook: Hook<"command_not_found">;
22
+ export default hook;
23
+ //# sourceMappingURL=command-not-found.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"command-not-found.d.ts","sourceRoot":"","sources":["../../src/hooks/command-not-found.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAIhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,mBAAmB,CAKnC,CAAC;AAEF,eAAe,IAAI,CAAC"}
@@ -0,0 +1,8 @@
1
+ import { rootUsage as e } from "../cli.js";
2
+ import { Errors as t } from "@oclif/core";
3
+ //#region src/hooks/command-not-found.ts
4
+ var n = async function(n) {
5
+ throw new t.CLIError(`command ${n.id} not found\n\n${e(this.config)}`, { exit: 2 });
6
+ };
7
+ //#endregion
8
+ export { n as default };
package/dist/index.js CHANGED
@@ -1,9 +1,9 @@
1
- import { n as e, t } from "./version-Be_NtSa4.js";
1
+ import { n as e, t } from "./version-DIJF4enj.js";
2
2
  import { isVersionRequest as n, main as r } from "./cli.js";
3
- import { i, n as a, o, r as s, t as c } from "./base-DGA47VMM.js";
4
- import { a as l, i as u, n as d, r as f } from "./plugins-ByvihMa0.js";
5
- import { n as p, t as m } from "./modules-CCvL41O_.js";
3
+ import { i, n as a, o, r as s, t as c } from "./base-DD0ONCEf.js";
4
+ import { a as l, i as u, n as d, r as f } from "./plugins-BO1uLsfi.js";
5
+ import { n as p, t as m } from "./modules-_4_rnXpw.js";
6
6
  import { i as h, n as g, r as _, t as v } from "./config-schema-Dp-vlxuR.js";
7
- import { a as y, i as b, n as x, o as S, r as C, t as w } from "./write-xs9kemgB.js";
8
- import { t as T } from "./flow-command-CPS23AjI.js";
7
+ import { a as y, i as b, n as x, o as S, r as C, t as w } from "./write-D462q_kk.js";
8
+ import { t as T } from "./flow-command-DK5LDrtg.js";
9
9
  export { T as FlowCommand, v as QUOIN_ENV_BINDINGS, g as QUOIN_PLUGIN_ID, c as QuoinCommand, _ as QuoinConfigSchema, b as UNRESOLVED_ORG_MESSAGE, w as createAuthoringPack, a as defaultModuleRoots, m as defaultModulesManifest, p as ensureDefaultModules, s as filamentModulesDir, i as findCatalogEntry, x as formatAuthoringPack, d as installPlugin, n as isVersionRequest, h as ixSchema, f as listPlugins, o as loadCatalog, r as main, y as originOrg, t as packageVersion, u as parseSourceArg, C as parseTypeList, l as removePlugin, S as resolveOrg, e as resolveVersion };
@@ -1,5 +1,5 @@
1
- import { a as e } from "./base-DGA47VMM.js";
2
- import { t } from "./plugins-ByvihMa0.js";
1
+ import { a as e } from "./base-DD0ONCEf.js";
2
+ import { t } from "./plugins-BO1uLsfi.js";
3
3
  import { readFileSync as n } from "node:fs";
4
4
  import { dirname as r, join as i } from "node:path";
5
5
  import { fileURLToPath as a } from "node:url";
@@ -1,4 +1,4 @@
1
- import { a as e, r as t } from "./base-DGA47VMM.js";
1
+ import { a as e, r as t } from "./base-DD0ONCEf.js";
2
2
  import { existsSync as n, readFileSync as r, rmSync as i } from "node:fs";
3
3
  import { basename as a, join as o } from "node:path";
4
4
  import { parse as s } from "yaml";
@@ -11,7 +11,7 @@ function a(e) {
11
11
  return e || i();
12
12
  }
13
13
  function o() {
14
- return a("0.12.0");
14
+ return a("0.12.2");
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-DGA47VMM.js";
1
+ import { i as e } from "./base-DD0ONCEf.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.12.0",
4
+ "version": "0.12.2",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -42,7 +42,10 @@
42
42
  },
43
43
  "plugins": [
44
44
  "@agent-ix/filament-plan-sync"
45
- ]
45
+ ],
46
+ "hooks": {
47
+ "command_not_found": "./dist/hooks/command-not-found"
48
+ }
46
49
  },
47
50
  "packageManager": "pnpm@10.33.4",
48
51
  "scripts": {
@@ -48,9 +48,11 @@ code, edit the plan, or change the matrix. Its only write is the SpecReview arti
48
48
  spec root, Test Matrix, and `org`/`component` for `ix://` URIs.
49
49
  1. **[Plan completion](references/step-2-plan-completion.md)**: Assert every `Task` is
50
50
  `done`; report incomplete/blocked tasks and stale `plan.md` checkboxes.
51
- 2. **[Matrix verification](references/step-3-matrix-verification.md)**: For every matrix
52
- Test Case, confirm a backing test with a matching tracking tag exists; flag unbacked
53
- rows, untracked tests, and inconsistent status markers.
51
+ 2. **[Matrix verification](references/step-3-matrix-verification.md)**: Run
52
+ `quire coverage --scope <root> --json` and interpret the report — unbacked rows, status
53
+ lies, untracked tests, and the backed/total rollup. The reconciliation is the engine's;
54
+ the severity and the verdict stay here. A repo whose module set declares no
55
+ `traceability:` model falls back to a grep index, declared as such.
54
56
  3. **[Underspecified code](references/step-4-underspecified-code.md)**: Find code/behavior
55
57
  with no owning requirement (reverse gap), plus stubs masquerading as complete.
56
58
  4. **[Semantic review](references/step-5-semantic-review.md)** *(OPTIONAL — ask first)*:
@@ -4,6 +4,10 @@
4
4
  test in the suite, identified by a matching **tracking tag** in the test code. This is the
5
5
  heart of gap-analysis: a matrix row marked ✅ means nothing unless a tagged test exists.
6
6
 
7
+ **This step no longer greps.** `quire coverage` computes the reconciliation deterministically
8
+ and reports it; this skill interprets the report and owns the judgement. Severity and verdict
9
+ stay here — the command reports and does not judge (quire-rs FR-050-CON-1).
10
+
7
11
  ## The matrix shape
8
12
 
9
13
  Built by `spec-matrix` (`quoin/skills/spec-matrix/SKILL.md`). Key tables:
@@ -12,10 +16,78 @@ Built by `spec-matrix` (`quoin/skills/spec-matrix/SKILL.md`). Key tables:
12
16
  `Test ID` = `TC-xxx`, `Traces To` = `FR-XXX-AC-X` etc., `Status` ∈ `✅ ⚠️ ❌ 🚧 ⛔`.
13
17
  - **Per-requirement coverage** — StR/US/FR/NFR → AC → TC → Status tables.
14
18
 
15
- ## Tracking-tag patterns in test code
19
+ What each column *means* is not this skill's knowledge either: the active module declares it
20
+ under `traceability:`, and `quire coverage` reads the same declaration the matrix contract is
21
+ validated against, so the two cannot drift.
22
+
23
+ ## Run the rollup
24
+
25
+ ```
26
+ quire coverage --scope <project_root> --json
27
+ ```
28
+
29
+ Do **not** pass `--strict`. Whether a gap blocks is this skill's verdict rule (Step 6), not
30
+ the command's exit code.
31
+
32
+ The report carries exactly the findings this step produces:
33
+
34
+ | Report field | What it is |
35
+ | --- | --- |
36
+ | `unbacked_rows` | A declared reference row whose trace targets have no backing `verifies` relation. Each carries `reference`, `document`, `row_id`, `target_ids`. |
37
+ | `status_lies` | A row whose status classes as `complete` while nothing backs it. Adds the authored `status` string. |
38
+ | `untracked_symbols` | A test carrying a trace tag that resolves to no declared row. Carries `path`, `symbol`, `trace_id`. |
39
+ | `groups` | Per minting document: `document`, `target`, `backed`, `total`. |
40
+ | `totals` | `backed` / `total` across the bundle. |
41
+
42
+ ## Reconcile, producing findings
43
+
44
+ | Report field | Finding | Severity |
45
+ | --- | --- | --- |
46
+ | `unbacked_rows` | Matrix overclaims coverage — the row names a criterion or test id nothing backs | `high` |
47
+ | `status_lies` | The row asserts `✅` over nothing. A subset of the above, and the worse half | `high` |
48
+ | `untracked_symbols` | A tagged test pointing at a row that does not exist — a stale tag, or a matrix that dropped a row | `medium` |
49
+ | Marker drift | Matrix `Status` inconsistent with a real run (`🚧` on a passing tagged test) | `low` |
50
+
51
+ `Refs` for each finding is the `row_id` and `document` the report gives, or `path::symbol`
52
+ for an untracked symbol. Do not re-derive them.
53
+
54
+ Marker drift is the one judgement the report cannot make — it needs the suite to have
55
+ actually run (step 4 below).
56
+
57
+ ## Two ways the report can mislead, and how to read it
16
58
 
17
- Tests declare which requirement/test-case they cover via tags in the code. The ecosystem
18
- uses these forms (grep for all of them, across `.py`/`.ts`/`.rs`):
59
+ - **`totals.total == 0` is not full coverage.** It means the declared model matched nothing
60
+ in this scope — no minting document was found. Recent `quire` prints `no rows matched`
61
+ rather than a percentage and fails `--strict` (quire-rs FR-050-AC-14); an older build
62
+ printed `0/0 rows backed (100%)` and exited 0. Treat a zero denominator as **no data**,
63
+ say so in `## Coverage`, and fall back (below). It is not a `PASS`.
64
+ - **An empty `unbacked_rows` proves nothing on its own.** It lists *reference rows* — cells
65
+ that point at trace ids. A repo whose module declares no such references has an empty list
66
+ regardless of how many tests are tagged. Read `groups` / `totals` alongside it.
67
+
68
+ ## Fallback: a repo on an older module set
69
+
70
+ `quire coverage` exits non-zero with a distinct diagnostic when no active module declares a
71
+ `traceability:` model (FR-050-AC-9). That is a real repo state, not an error to swallow —
72
+ `spec-artifacts-process` only began declaring the model at the release carrying FR-004.
73
+
74
+ When the command refuses, or reports a zero denominator, fall back to the grep index below
75
+ and **say which path ran** in the SpecReview's `## Coverage` section:
76
+
77
+ ```
78
+ Reconciliation: quire coverage (module spec-artifacts-process 0.11.0)
79
+ Reconciliation: grep fallback — no active module declares a traceability model
80
+ ```
81
+
82
+ A finding derived from the fallback is weaker and should be read as such: grep matches a tag
83
+ wherever it sits in a file, including places the engine will not bind it. In quoin, ~15 tags
84
+ sat above a `describe(` block, which registers no symbol — greppable, and invisible to the
85
+ engine (agent-ix/quoin#61). **Never present a grep count as a coverage figure** without
86
+ naming it as a fallback.
87
+
88
+ ### The fallback index
89
+
90
+ Grep the test tree across `.py` / `.ts` / `.rs` for every form:
19
91
 
20
92
  | Form | Example |
21
93
  | --- | --- |
@@ -24,31 +96,29 @@ uses these forms (grep for all of them, across `.py`/`.ts`/`.rs`):
24
96
  | Module docstring | `"""Tests for FR-017: Context Management."""` |
25
97
  | Test-case id comment / name | `# TC-041`, or a test whose name maps to `TC-041` |
26
98
 
27
- ## Process
28
-
29
- 1. **Parse the matrix.** Extract the set of declared Test Cases `{TC-xxx → (Traces To, Status)}`.
30
- 2. **Index the suite.** Grep the test tree for every tracking tag form above; build
31
- `{tag → [test file :: test name]}` for `TC-xxx`, `FR-xxx`, `FR-xxx-AC-x`.
32
- 3. **Reconcile, producing findings:**
33
- - **Unbacked matrix row** — a `TC-xxx` (or its `Traces To` requirement) with **no**
34
- matching tag in any test → `high` finding (the matrix overclaims coverage).
35
- - **Status lie** — a row marked `✅ Complete` but its test is missing, skipped
36
- (`pytest.skip`), or its requirement has no tagged test → `high`.
37
- - **Untracked test** — a real test that exercises behavior but carries **no** tracking
38
- tag and is **absent** from the matrix → `medium` (coverage exists but isn't traced).
39
- - **Marker drift** — matrix `Status` inconsistent with reality (e.g. `🚧` for a passing
40
- tagged test, or `✅` for a `⚠️`-quality test) → `low`.
41
- 4. **Optionally run the suite.** If the user wants execution evidence (not just static
42
- tag-matching), run `make test` and note failures/skips against matrix rows. Don't block
43
- on this if the environment can't run tests; say so.
44
- 5. **Rollup.** Count matrix Test Cases backed-by-tagged-test / total — feeds `## Coverage`.
99
+ Build `{tag → [test file :: test name]}`, then reconcile against the matrix by hand for the
100
+ same four finding kinds.
101
+
102
+ ## Optionally run the suite
103
+
104
+ If the user wants execution evidence rather than static reconciliation, run `make test` and
105
+ note failures and skips against matrix rows. This is what turns marker drift from a guess
106
+ into a finding. Don't block on it if the environment can't run tests; say so.
107
+
108
+ ## Rollup
109
+
110
+ `totals.backed` / `totals.total` feeds `## Coverage`, with the per-document breakdown from
111
+ `groups` where it helps. Report the numbers the tool produced — do not recompute them, and
112
+ do not quote a figure from an earlier run whose provenance you cannot state.
45
113
 
46
114
  ## Output of this step
47
115
 
48
- Findings (unbacked rows, status lies, untracked tests, marker drift) with `Refs` =
49
- `TC-xxx` / `FR-xxx` / test path, plus the backed/total count.
116
+ Findings (unbacked rows, status lies, untracked tests, marker drift) with `Refs` from the
117
+ report, the backed/total count, and which reconciliation path ran.
50
118
 
51
119
  ## Notes
52
120
 
53
- - A tag match proves *traceability*, not *correctness* — whether the test is a good test is
121
+ - A backed row proves *traceability*, not *correctness* — whether the test is a good test is
54
122
  Step 4 (underspecified/stub) and Step 5 (semantic). Keep this step about presence + trace.
123
+ - The command performs no network or service I/O and executes none of the code it reads
124
+ (FR-050-CON-2, FR-051-CON-1), so it is safe to run in any repo.
@@ -58,12 +58,17 @@ are extra sections (allowed).
58
58
 
59
59
  ## Coverage
60
60
 
61
+ - Reconciliation: quire coverage (module <name> <version>) | grep fallback — no active module declares a traceability model
61
62
  - Tasks done: X / Y
62
- - Matrix Test Cases backed by tagged test: X / Y
63
+ - Rows backed by a tagged test: X / Y (from `totals`; `0 / 0` means the model matched nothing, not full coverage)
63
64
  - Untraced behaviors / stubs: N
64
65
  - Semantic review: ran over N requirements | skipped
65
66
  ```
66
67
 
68
+ The reconciliation line is not optional. A number from the engine and a number from a grep
69
+ are not the same claim — grep matches a tag wherever it sits, including places the engine
70
+ will not bind it — and a reader cannot tell which they are looking at unless it says so.
71
+
67
72
  ### Findings table contract (validated)
68
73
 
69
74
  - Headers EXACTLY: `ID | Severity | Summary | Refs`.
@@ -3,9 +3,8 @@ name: spec-correctness
3
3
  description: Turn classified acceptance criteria into runnable property tests. Consumes
4
4
  `quire properties --json` per-criterion records, grounds each criterion's domain,
5
5
  precondition and oracle in the spec and the code, and emits property tests in the
6
- repo's own harness (proptest / fast-check / hypothesis) keyed on `row_id`. Settled
7
- criteria land unattended; candidates and the LLM second pass over example/unclassified
8
- criteria land inert in a review queue.
6
+ repo's own harness (proptest / fast-check / hypothesis) keyed on `row_id`. Emits a
7
+ validated SpecReview recording every criterion it could not ground and why.
9
8
  ---
10
9
 
11
10
  # Spec Correctness
@@ -68,8 +67,8 @@ whether existing tests are good (`gap-analysis`).
68
67
  with the `row_id` tracking tags and the provenance line.
69
68
  5. **[Second pass](references/step-5-second-pass.md)**: the LLM pass over `example`,
70
69
  `unclassified`, and anything step 2 refused to ground.
71
- 6. **[Review queue](references/step-6-review-queue.md)**: the queue file, the inert
72
- markers, and the acceptance procedure.
70
+ 6. **[Review artifact](references/step-6-review-artifact.md)**: the `SpecReview` at
71
+ `reviews/YY-MM-DD-<slug>.md` recording what could not be grounded, and why.
73
72
  7. **[Report and handoff](references/step-7-report-and-handoff.md)**: the run report, the
74
73
  `Property` rows for `spec-matrix`, and the reconciliation check against `gap-analysis`.
75
74
 
@@ -80,14 +79,13 @@ when the residue is large (say, more than 30 records).
80
79
 
81
80
  | Path | What |
82
81
  | --- | --- |
83
- | `tests/props/<per-harness naming>` | Unattended property tests (`extraction: extractable`, grounded) |
84
- | `tests/props/_review/…` (Rust: `tests/props_review_fr_NNN.rs`) | Queued tests — inert until accepted |
85
- | `tests/props/QUEUE.md` | The review queue and the run report |
86
-
87
- > **Why the queue is not a `SpecReview`.** `SpecReview.analysis` is a closed enum in
88
- > `spec-artifacts-process` with no `spec-correctness` value, so a review file under
89
- > `reviews/` would fail `quire validate`. The queue lives in the test tree, outside every
90
- > spec validation glob. Adding the enum value upstream is a follow-up, not a prerequisite.
82
+ | `tests/props/<per-harness naming>` | Property tests, all of them runnable |
83
+ | `reviews/YY-MM-DD-<slug>.md` | A `SpecReview` (`analysis: spec-correctness`) recording what could not be grounded |
84
+
85
+ Nothing else is written to the tree (FR-028-CON-1). No skipped tests, no `_review/`
86
+ directory, no ad-hoc report file. A generated test arrives in a pull request, and that is
87
+ what puts it under review; the artifact carries the one thing a PR does not — why a
88
+ criterion was left ungrounded.
91
89
 
92
90
  ## Two facts that will bite if you assume otherwise
93
91
 
@@ -10,7 +10,7 @@ it is the FR-047 grammar axis, not the property axis.
10
10
 
11
11
  ## `round-trip`
12
12
 
13
- - **Needs** two symbols, an encoder and its inverse. Only one found → queue.
13
+ - **Needs** two symbols, an encoder and its inverse. Only one found → no test, one finding.
14
14
  - **Domain** the *inner* type — generate `x`, not the encoded form, so every value is
15
15
  reachable and shrinking is meaningful.
16
16
  - **Oracle** `dec(enc(x)) == x`.
@@ -78,7 +78,7 @@ it is the FR-047 grammar axis, not the property axis.
78
78
  parallel mode when the op set is large.
79
79
  - **TypeScript** `fc.scheduler()` — deterministic and shrinkable.
80
80
  - **Python** hypothesis has no interleaving scheduler. Emit a `RuleBasedStateMachine`
81
- sketch over the async model, **always queued**, never unattended.
81
+ sketch over the async model, **always with a finding** recording the downgrade.
82
82
 
83
83
  ## `universal`
84
84
 
@@ -92,7 +92,7 @@ it is the FR-047 grammar axis, not the property axis.
92
92
 
93
93
  - **Not a property.** Step 5 owns it.
94
94
  - May become a reclassified property (with citations) or a `Unit` witness test. A witness
95
- is queued and is **not** counted as property coverage.
95
+ is recorded as a finding and is **not** counted as property coverage.
96
96
 
97
97
  ## `unclassified`
98
98