@agent-ix/quoin 0.3.7 → 0.4.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.
package/README.md CHANGED
@@ -15,6 +15,57 @@ workflows agents need to write and validate specs directly as Markdown.
15
15
 
16
16
  `quoin` is built on the [Quire](https://github.com/agent-ix/quire-rs) document standard and validation engine by Agent-IX.
17
17
 
18
+ > **Why:** AI agents write code fast but drift from vague intent. Quoin makes the spec the source of truth — your agent authors a validated, traceable spec first, then plans and builds against it.
19
+
20
+ ## How
21
+
22
+ In Claude Code, Codex, or the coding agent of your choice:
23
+
24
+ #### 1. Ideate & Specify
25
+
26
+ Ideate, then pass your idea to `/specify`. A `specification` containing `user stories`, `functional requirements`,
27
+ `stakeholder requirements`, `non-functional requirements`, and other artifacts will be created.
28
+
29
+ ```
30
+ > /specify an electron app for tracking spice production
31
+ ```
32
+
33
+ #### 2. Spec Review
34
+
35
+ Use `/spec-review` for agent-assisted review. Multiple analysis tasks will run in parallel and output `Reviews`
36
+ with `Findings` and suggested fixes.
37
+
38
+ ```
39
+ > /spec-review review the specs for the spice production tracker.
40
+ ```
41
+
42
+ #### 3. Convert to plans
43
+
44
+ Build the test `traceability matrix` and `plan`. These skills will break the work down into a `plan`
45
+ with multiple `tasks`.
46
+
47
+ ```
48
+ > /spec-matrix /spec-to-plan prep the spice tracking app for coding
49
+ ```
50
+
51
+ #### 4. Implement!
52
+
53
+ Call `/implement-plan` to trigger your coding agent to begin work on the plan.
54
+
55
+ ```
56
+ > /implement-plan build the spice tracking app
57
+ ```
58
+
59
+ #### 5. Gap review
60
+
61
+ `/gap-analysis` validates that the `UserStory` and `Functional Requirements` are implemented and tested using the `traceability matrix`
62
+ as the guide. `/gap-analysis` will optionally perform a _semantic_ comparison of `spec`, `code`, and `tests` to ensure the
63
+ `plan` is faithfully implemented.
64
+
65
+ ```
66
+ > /gap-analysis
67
+ ```
68
+
18
69
  ## What's included
19
70
 
20
71
  The default module set defines the spec archetypes and domain-object vocabulary.
@@ -65,7 +116,7 @@ Multi-agent workflows that fan out, run lenses in parallel, and synthesize resul
65
116
  ## Install
66
117
 
67
118
  Installing quoin into Claude is **two steps**: the CLI (from public npm) and the plugin
68
- that adds the [skills](#skills) and [workflows](#workflows) to Claude Code. No Anthropic API
119
+ that adds the [skills](#agent-skills) and [workflows](#agent-workflows) to Claude Code. No Anthropic API
69
120
  key is required — your Claude subscription is used.
70
121
 
71
122
  **1. Install the CLIs** (`quoin` plus `ix-flow`, which runs the workflow lifecycle commands):
@@ -89,9 +140,9 @@ the agent.
89
140
  ### skills & workflows
90
141
 
91
142
  The primary way users author specs is by asking an agent, which invokes the bundled
92
- [skills](#skills) and [workflows](#workflows).
143
+ [skills](#agent-skills) and [workflows](#agent-workflows).
93
144
 
94
- ### ClI commands
145
+ ### CLI commands
95
146
 
96
147
  Inspect the spec vocabulary and manage installed modules:
97
148
 
@@ -28,13 +28,13 @@ entries:
28
28
  ref: v0.2.0
29
29
 
30
30
  - name: spec-artifacts-process
31
- version: "0.3.0"
31
+ version: "0.4.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.3.0
37
+ ref: v0.4.0
38
38
 
39
39
  - name: spec-objects-business
40
40
  version: "0.3.0"
@@ -1,14 +1,14 @@
1
1
  import { existsSync as e, readFileSync as t, readdirSync as n, rmSync as r, statSync as i } from "node:fs";
2
2
  import { basename as a, dirname as o, join as s, resolve as c } from "node:path";
3
3
  import { fileURLToPath as l } from "node:url";
4
- import { configureRuntimeContext as u } from "@agent-ix/ix-cli-core";
5
- import { homedir as d } from "node:os";
6
- import { parse as f } from "yaml";
7
- import { installEntry as p, readRegistry as m, reconcile as ee, validateMarketplaceManifest as h, writeRegistry as g } from "@agent-ix/ts-plugin-kit";
4
+ import { configureRuntimeContext as u, runSelfUpdate as d } from "@agent-ix/ix-cli-core";
5
+ import { homedir as f } from "node:os";
6
+ import { parse as p } from "yaml";
7
+ import { installEntry as ee, readRegistry as m, reconcile as h, validateMarketplaceManifest as te, writeRegistry as g } from "@agent-ix/ts-plugin-kit";
8
8
  import { spawn as _ } from "node:child_process";
9
9
  //#region src/catalog.ts
10
10
  function v() {
11
- return process.env.IX_HOME && process.env.IX_HOME.length > 0 ? process.env.IX_HOME : s(d(), ".ix");
11
+ return process.env.IX_HOME && process.env.IX_HOME.length > 0 ? process.env.IX_HOME : s(f(), ".ix");
12
12
  }
13
13
  function y(e = v()) {
14
14
  return s(e, "filament", "modules");
@@ -23,22 +23,22 @@ function b(t = v()) {
23
23
  function x(e = b()) {
24
24
  let n = [], r = [], i = /* @__PURE__ */ new Set(), o = /* @__PURE__ */ new Set();
25
25
  for (let c of e) {
26
- let e = w(c);
26
+ let e = ne(c);
27
27
  if (!e || i.has(e)) continue;
28
28
  i.add(e);
29
- let l = f(t(s(e, "manifest.yaml"), "utf8")), u = D(l.name) ?? a(e);
29
+ let l = p(t(s(e, "manifest.yaml"), "utf8")), u = E(l.name) ?? a(e);
30
30
  if (o.has(u)) continue;
31
31
  o.add(u);
32
- let d = E(l.artifact_types), p = E(l.object_types);
32
+ let d = T(l.artifact_types), f = T(l.object_types);
33
33
  n.push({
34
34
  name: u,
35
- version: D(l.version),
35
+ version: E(l.version),
36
36
  root: e,
37
37
  artifactTypes: d.map((e) => String(e.name)),
38
- objectTypes: p.map((e) => String(e.name))
38
+ objectTypes: f.map((e) => String(e.name))
39
39
  });
40
40
  for (let t of d) {
41
- let n = String(t.name), i = D(t.frontmatter_schema_ref);
41
+ let n = String(t.name), i = E(t.frontmatter_schema_ref);
42
42
  r.push({
43
43
  name: n,
44
44
  kind: "artifact",
@@ -46,24 +46,24 @@ function x(e = b()) {
46
46
  moduleRoot: e,
47
47
  schemaRef: i,
48
48
  schemaPath: i ? s(e, i) : void 0,
49
- skeletonPath: T(e, n)
49
+ skeletonPath: w(e, n)
50
50
  });
51
51
  }
52
- for (let t of p) {
52
+ for (let t of f) {
53
53
  let n = String(t.name);
54
54
  r.push({
55
55
  name: n,
56
56
  kind: "object",
57
57
  moduleName: u,
58
58
  moduleRoot: e,
59
- skeletonPath: T(e, n)
59
+ skeletonPath: w(e, n)
60
60
  });
61
61
  }
62
62
  }
63
63
  return {
64
64
  modules: n,
65
65
  entries: r,
66
- duplicates: te(r)
66
+ duplicates: D(r)
67
67
  };
68
68
  }
69
69
  function S(e, t) {
@@ -73,7 +73,7 @@ function S(e, t) {
73
73
  function C(e) {
74
74
  return e.toLowerCase();
75
75
  }
76
- function w(t) {
76
+ function ne(t) {
77
77
  let r = c(t);
78
78
  if (e(r)) {
79
79
  if (e(s(r, "manifest.yaml"))) return r;
@@ -83,16 +83,16 @@ function w(t) {
83
83
  }
84
84
  }
85
85
  }
86
- function T(t, n) {
86
+ function w(t, n) {
87
87
  return [s(t, "skeletons", `${n}.md`), s(t, "skeletons", `${n.toLowerCase()}.md`)].find((t) => e(t));
88
88
  }
89
- function E(e) {
89
+ function T(e) {
90
90
  return Array.isArray(e) ? e.filter((e) => !!e && typeof e == "object" && "name" in e) : [];
91
91
  }
92
- function D(e) {
92
+ function E(e) {
93
93
  return typeof e == "string" ? e : void 0;
94
94
  }
95
- function te(e) {
95
+ function D(e) {
96
96
  let t = /* @__PURE__ */ new Map();
97
97
  for (let n of e) {
98
98
  let e = `${n.kind}:${n.name}`, r = t.get(e) ?? /* @__PURE__ */ new Set();
@@ -156,7 +156,7 @@ function A(e) {
156
156
  };
157
157
  }
158
158
  function j(e, t = v()) {
159
- return p({ source: A(e) }, k(t));
159
+ return ee({ source: A(e) }, k(t));
160
160
  }
161
161
  function M(e = v()) {
162
162
  return m(O(e)).plugins;
@@ -174,7 +174,7 @@ function N(e, t = v()) {
174
174
  function P(n) {
175
175
  let r = e(s(n, "manifest.yaml")) ? s(n, "manifest.yaml") : s(n, a(n), "manifest.yaml");
176
176
  if (!e(r)) throw Error(`no manifest.yaml found under ${n}`);
177
- let i = f(t(r, "utf8"));
177
+ let i = p(t(r, "utf8"));
178
178
  if (typeof i.name != "string" || i.name.length === 0) throw Error(`manifest ${r} has no name`);
179
179
  return i.name;
180
180
  }
@@ -184,10 +184,10 @@ function F() {
184
184
  return o(o(l(import.meta.url)));
185
185
  }
186
186
  function I() {
187
- return h(f(t(s(F(), "default-modules.yaml"), "utf8")));
187
+ return te(p(t(s(F(), "default-modules.yaml"), "utf8")));
188
188
  }
189
189
  function L(e = v(), t = I()) {
190
- ee(t, {
190
+ h(t, {
191
191
  ...k(e),
192
192
  mode: "lazy"
193
193
  });
@@ -211,8 +211,8 @@ var R = {
211
211
  function z() {
212
212
  return Object.keys(R);
213
213
  }
214
- async function ne(e, t = {}) {
215
- let n = B(e), r = v(), i = [
214
+ async function B(e, t = {}) {
215
+ let n = V(e), r = v(), i = [
216
216
  "run",
217
217
  e,
218
218
  "--path",
@@ -224,16 +224,16 @@ async function ne(e, t = {}) {
224
224
  ];
225
225
  t.id && i.push("--id", t.id), t.json && i.push("--json");
226
226
  for (let e of t.target ?? []) i.push("--target", e);
227
- await H(i);
227
+ await U(i);
228
228
  }
229
- function B(t) {
229
+ function V(t) {
230
230
  let n = R[t];
231
231
  if (!n) throw Error(`unknown spec flow ${t}`);
232
232
  let r = [
233
233
  process.env.IX_SPEC_WORKFLOWS_ROOT,
234
- V(),
234
+ H(),
235
235
  s(o(c(process.cwd())), "ix-spec-workflows"),
236
- s(d(), ".ix", "plugins", "ix-spec-workflows")
236
+ s(f(), ".ix", "plugins", "ix-spec-workflows")
237
237
  ].filter((e) => !!e);
238
238
  for (let t of r) {
239
239
  let r = s(t, n.packageSkill, "workflow-assets", "skills", n.runtimeSkill);
@@ -241,10 +241,10 @@ function B(t) {
241
241
  }
242
242
  throw Error(`could not find ix-spec workflow skill ${n.runtimeSkill}; set IX_SPEC_WORKFLOWS_ROOT`);
243
243
  }
244
- function V() {
244
+ function H() {
245
245
  return s(o(o(l(import.meta.url))), "skills");
246
246
  }
247
- async function H(e) {
247
+ async function U(e) {
248
248
  await new Promise((t, n) => {
249
249
  let r = _("ix-flow", e, { stdio: "inherit" });
250
250
  r.on("error", n), r.on("close", (e) => {
@@ -258,10 +258,10 @@ async function H(e) {
258
258
  }
259
259
  //#endregion
260
260
  //#region src/write.ts
261
- function U(e) {
261
+ function W(e) {
262
262
  return (Array.isArray(e) ? e : e ? [e] : []).flatMap((e) => e.split(",")).map((e) => e.trim()).filter(Boolean);
263
263
  }
264
- function W(t, n, r) {
264
+ function G(t, n, r) {
265
265
  if (r.length === 0) throw Error("write requires --types <type[,type...]>");
266
266
  let a = c(n);
267
267
  if (!e(a) || !i(a).isDirectory()) throw Error(`write repo_dir is not a directory: ${n}`);
@@ -270,16 +270,16 @@ function W(t, n, r) {
270
270
  types: r.map((e) => {
271
271
  let n = S(t, e);
272
272
  if (!n) throw Error(`catalog type not found: ${e}\nAvailable types: ${t.entries.map((e) => e.name).sort((e, t) => e.localeCompare(t)).join(", ")}`);
273
- return K(n);
273
+ return q(n);
274
274
  }),
275
275
  validation: {
276
- command: `quire validate --scope ${q(a)} "spec/**/*.md"`,
276
+ command: `quire validate --scope ${J(a)} "spec/**/*.md"`,
277
277
  scope: a,
278
278
  globs: ["spec/**/*.md"]
279
279
  }
280
280
  };
281
281
  }
282
- function G(e) {
282
+ function K(e) {
283
283
  let t = [
284
284
  "quoin write",
285
285
  "",
@@ -290,7 +290,7 @@ function G(e) {
290
290
  for (let n of e.types) t.push(`- ${n.name} (${n.kind})`), t.push(` module: ${n.moduleName}`), t.push(` module_root: ${n.moduleRoot}`), n.skeletonPath && t.push(` skeleton: ${n.skeletonPath}`), n.schemaPath && t.push(` schema: ${n.schemaPath}`), !n.skeletonPath && !n.schemaPath && t.push(" contract: manifest only");
291
291
  return t.push(""), t.push("Author files directly in the repo, then validate changed spec files."), t.push(`Validate scope: ${e.validation.scope}`), t.push(`Validate command: ${e.validation.command}`), t.join("\n");
292
292
  }
293
- function K(e) {
293
+ function q(e) {
294
294
  return {
295
295
  name: e.name,
296
296
  kind: e.kind,
@@ -300,24 +300,24 @@ function K(e) {
300
300
  ...e.skeletonPath ? { skeletonPath: e.skeletonPath } : {}
301
301
  };
302
302
  }
303
- function q(e) {
303
+ function J(e) {
304
304
  return /^[A-Za-z0-9_./:-]+$/.test(e) ? e : `'${e.replaceAll("'", "'\\''")}'`;
305
305
  }
306
306
  //#endregion
307
307
  //#region src/cli.ts
308
- var J = "quoin\n\nSpec workflow and catalog CLI for Agent IX.\n\nquoin starts spec-domain work. ix-flow resumes, advances, acknowledges gates,\nand inspects workflow runs created by quoin.\n\nDefault modules (installed on first use into ~/.ix/filament/modules):\n Artifact modules: spec-artifacts-iso, spec-artifacts-app, spec-artifacts-process\n Object modules: spec-objects-business, spec-objects-architecture,\n spec-objects-enterprise, spec-objects-operational,\n spec-objects-security\n Workflows: review, matrix, to-plan\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n quoin catalog list|validate\n quoin catalog show <type>\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin review|matrix|to-plan [--target <ref>...]\n\nGlobal flags:\n --json\n --config-root <dir> Defaults to ~/.ix\n\nExamples:\n quoin catalog list\n quoin catalog show FR\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin write . --types FR,domain\n ix-flow status <run-id>\n", Y = "quoin write\n\nBuild an authoring pack for spec files an agent is about to create or edit.\n\nPass the target repository and the artifact/object types involved in the work.\nquoin resolves those types from the active catalog and returns the local\nskeletons, schemas, module roots, and Quire validation command for the repo.\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n\nExamples:\n quoin write . --types FR\n quoin write . --types FR,domain,entity\n quoin write ../my-service --types fr,DOMAIN --json\n\nNotes:\n - Type lookup is case-insensitive; FR and fr are the same type.\n - Types can be artifacts or objects from the default module set or plugins.\n - Use the returned skeletons and schemas as the authoring contract.\n - Run the returned Quire command after editing spec files.\n", X = "quoin catalog\n\nInspect the active artifact/object catalog.\n\nThe catalog is assembled from, in order:\n 1. QUOIN_MODULE_PATHS\n 2. modules installed under ~/.ix/filament/modules\n\nThe default module set is installed there automatically on first catalog access,\nand updated by \"quoin plugin install\". The same directory is read by quire-rs.\n\nDefault artifact modules:\n spec-artifacts-iso FR, NFR, StR, US, IT, TC, AC, CON, Spec\n spec-artifacts-app app-level artifacts\n spec-artifacts-process plans, reviews, matrices, ADRs, tasks, findings\n\nDefault object modules:\n spec-objects-business\n spec-objects-architecture\n spec-objects-enterprise\n spec-objects-operational\n spec-objects-security\n\nUsage:\n quoin catalog list\n quoin catalog show <type>\n quoin catalog validate\n\nExamples:\n quoin catalog show FR\n quoin catalog show entity\n quoin catalog validate --json\n", re = "quoin plugin\n\nInstall and manage user/community spec modules.\n\nPlugins add or override artifact/object modules under ~/.ix/filament/modules.\nUse \"catalog list\" to see the full active catalog, including default modules and\nplugins.\n\nSupported install sources:\n path:<dir> Use a local directory containing manifest.yaml\n github:<owner>/<repo> Clone a GitHub repository (manifest at root)\n github:<owner>/<repo>@<ref> Pin to a tag, branch, or sha\n github:<owner>/<repo>//<subdir> Manifest in a monorepo subdirectory (@<ref> ok)\n\nUsage:\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin plugin ensure-defaults\n\nExamples:\n quoin plugin install path:../spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-security//spec_objects_security@v0.1.1\n quoin plugin list\n quoin plugin ensure-defaults\n", ie = "quoin workflows\n\nStart bundled spec review/planning workflows. quoin creates the workflow run in ~/.ix/flows.\nUse ix-flow to inspect, resume, advance phases, and acknowledge human gates.\n\nAvailable workflow launchers:\n review Run a composite spec review\n matrix Build or update a requirements test matrix\n to-plan Convert accepted requirements into an implementation plan\n\nUsage:\n quoin review|matrix|to-plan [--target <ref>...]\n\nExamples:\n quoin review --target spec/\n quoin matrix --target spec/\n ix-flow status <run-id>\n ix-flow resume <run-id>\n";
309
- async function ae(e) {
310
- let t = ue(e);
308
+ var Y = "quoin\n\nSpec workflow and catalog CLI for Agent IX.\n\nquoin starts spec-domain work. ix-flow resumes, advances, acknowledges gates,\nand inspects workflow runs created by quoin.\n\nDefault modules (installed on first use into ~/.ix/filament/modules):\n Artifact modules: spec-artifacts-iso, spec-artifacts-app, spec-artifacts-process\n Object modules: spec-objects-business, spec-objects-architecture,\n spec-objects-enterprise, spec-objects-operational,\n spec-objects-security\n Workflows: review, matrix, to-plan\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n quoin catalog list|validate\n quoin catalog show <type>\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin review|matrix|to-plan [--target <ref>...]\n quoin update [--check] [--registry <url>]\n\nGlobal flags:\n --json\n --config-root <dir> Defaults to ~/.ix\n\nExamples:\n quoin catalog list\n quoin catalog show FR\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin write . --types FR,domain\n ix-flow status <run-id>\n", X = "quoin write\n\nBuild an authoring pack for spec files an agent is about to create or edit.\n\nPass the target repository and the artifact/object types involved in the work.\nquoin resolves those types from the active catalog and returns the local\nskeletons, schemas, module roots, and Quire validation command for the repo.\n\nUsage:\n quoin write <repo_dir> --types <type[,type...]>\n\nExamples:\n quoin write . --types FR\n quoin write . --types FR,domain,entity\n quoin write ../my-service --types fr,DOMAIN --json\n\nNotes:\n - Type lookup is case-insensitive; FR and fr are the same type.\n - Types can be artifacts or objects from the default module set or plugins.\n - Use the returned skeletons and schemas as the authoring contract.\n - Run the returned Quire command after editing spec files.\n", re = "quoin catalog\n\nInspect the active artifact/object catalog.\n\nThe catalog is assembled from, in order:\n 1. QUOIN_MODULE_PATHS\n 2. modules installed under ~/.ix/filament/modules\n\nThe default module set is installed there automatically on first catalog access,\nand updated by \"quoin plugin install\". The same directory is read by quire-rs.\n\nDefault artifact modules:\n spec-artifacts-iso FR, NFR, StR, US, IT, TC, AC, CON, Spec\n spec-artifacts-app app-level artifacts\n spec-artifacts-process plans, reviews, matrices, ADRs, tasks, findings\n\nDefault object modules:\n spec-objects-business\n spec-objects-architecture\n spec-objects-enterprise\n spec-objects-operational\n spec-objects-security\n\nUsage:\n quoin catalog list\n quoin catalog show <type>\n quoin catalog validate\n\nExamples:\n quoin catalog show FR\n quoin catalog show entity\n quoin catalog validate --json\n", ie = "quoin plugin\n\nInstall and manage user/community spec modules.\n\nPlugins add or override artifact/object modules under ~/.ix/filament/modules.\nUse \"catalog list\" to see the full active catalog, including default modules and\nplugins.\n\nSupported install sources:\n path:<dir> Use a local directory containing manifest.yaml\n github:<owner>/<repo> Clone a GitHub repository (manifest at root)\n github:<owner>/<repo>@<ref> Pin to a tag, branch, or sha\n github:<owner>/<repo>//<subdir> Manifest in a monorepo subdirectory (@<ref> ok)\n\nUsage:\n quoin plugin install <path:...|github:...>\n quoin plugin list\n quoin plugin remove <name>\n quoin plugin ensure-defaults\n\nExamples:\n quoin plugin install path:../spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-custom\n quoin plugin install github:agent-ix/spec-objects-security//spec_objects_security@v0.1.1\n quoin plugin list\n quoin plugin ensure-defaults\n", ae = "quoin update\n\nCheck for and install the latest published quoin.\n\nquoin is distributed on the public npm registry as @agent-ix/quoin. This command\nqueries the registry for the latest version, compares it to the running version,\nand (unless --check) runs npm install -g to upgrade in place.\n\nUsage:\n quoin update [--check] [--registry <url>]\n\nFlags:\n --check Report whether an update is available; do not install.\n --registry <url> Force an npm registry to query/install from. Defaults\n to your npm config (the registry @agent-ix resolves to,\n i.e. however quoin was installed). Pass\n https://registry.npmjs.org/ for public npm, or\n http://npm.ix/ for local dev snapshots.\n\nExamples:\n quoin update\n quoin update --check\n quoin update --registry http://npm.ix/\n", oe = "quoin workflows\n\nStart bundled spec review/planning workflows. quoin creates the workflow run in ~/.ix/flows.\nUse ix-flow to inspect, resume, advance phases, and acknowledge human gates.\n\nAvailable workflow launchers:\n review Run a composite spec review\n matrix Build or update a requirements test matrix\n to-plan Convert accepted requirements into an implementation plan\n\nUsage:\n quoin review|matrix|to-plan [--target <ref>...]\n\nExamples:\n quoin review --target spec/\n quoin matrix --target spec/\n ix-flow status <run-id>\n ix-flow resume <run-id>\n";
309
+ async function se(e) {
310
+ let t = pe(e);
311
311
  if (t.flags.version || t.flags.v || t.command === "version") {
312
312
  console.log(Z());
313
313
  return;
314
314
  }
315
315
  if (!t.command) {
316
- console.log(J);
316
+ console.log(Y);
317
317
  return;
318
318
  }
319
319
  if (t.flags.help || t.flags.h) {
320
- console.log(oe(t));
320
+ console.log(ce(t));
321
321
  return;
322
322
  }
323
323
  let n = Q(t, "config-root") ?? v();
@@ -326,32 +326,42 @@ async function ae(e) {
326
326
  configNamespace: "ix",
327
327
  projectConfigRoot: `${process.cwd()}/.ix`,
328
328
  projectConfigEnabled: t.flags["no-project-config"] !== !0
329
- }), t.command === "catalog") return ce(t);
330
- if (t.command === "plugin") return le(t);
331
- if (t.command === "write") return se(t);
332
- if (z().includes(t.command)) return ne(t.command, {
329
+ }), t.command === "update") return ue(t);
330
+ if (t.command === "catalog") return de(t);
331
+ if (t.command === "plugin") return fe(t);
332
+ if (t.command === "write") return le(t);
333
+ if (z().includes(t.command)) return B(t.command, {
333
334
  json: t.flags.json === !0,
334
335
  id: Q(t, "id"),
335
336
  target: $(t, "target")
336
337
  });
337
- throw Error(`unknown command ${t.command}\n\n${J}`);
338
+ throw Error(`unknown command ${t.command}\n\n${Y}`);
338
339
  }
339
340
  function Z() {
340
341
  let e = o(o(l(import.meta.url))), n = JSON.parse(t(s(e, "package.json"), "utf8"));
341
342
  if (typeof n.version != "string") throw Error("package.json version is missing");
342
343
  return n.version;
343
344
  }
344
- function oe(e) {
345
- return e.command === "write" ? Y : e.command === "catalog" ? X : e.command === "plugin" ? re : z().includes(e.command) ? ie : J;
345
+ function ce(e) {
346
+ return e.command === "update" ? ae : e.command === "write" ? X : e.command === "catalog" ? re : e.command === "plugin" ? ie : z().includes(e.command) ? oe : Y;
346
347
  }
347
- function se(e) {
348
+ function le(e) {
348
349
  let [t] = e.positionals;
349
- if (!t) throw Error(`write requires <repo_dir>\n\n${Y}`);
350
+ if (!t) throw Error(`write requires <repo_dir>\n\n${X}`);
350
351
  L();
351
- let n = W(x(), t, U($(e, "types")));
352
- console.log(e.flags.json ? JSON.stringify(n, null, 2) : G(n));
352
+ let n = G(x(), t, W($(e, "types")));
353
+ console.log(e.flags.json ? JSON.stringify(n, null, 2) : K(n));
354
+ }
355
+ async function ue(e) {
356
+ await d({
357
+ packageName: "@agent-ix/quoin",
358
+ currentVersion: Z(),
359
+ header: "quoin update",
360
+ registry: Q(e, "registry"),
361
+ check: e.flags.check === !0
362
+ });
353
363
  }
354
- function ce(e) {
364
+ function de(e) {
355
365
  L();
356
366
  let t = x();
357
367
  switch (e.subcommand) {
@@ -387,7 +397,7 @@ function ce(e) {
387
397
  default: throw Error(`unknown catalog command ${e.subcommand}`);
388
398
  }
389
399
  }
390
- function le(e) {
400
+ function fe(e) {
391
401
  switch (e.subcommand) {
392
402
  case "list":
393
403
  case void 0:
@@ -414,7 +424,7 @@ function le(e) {
414
424
  default: throw Error(`unknown plugin command ${e.subcommand}`);
415
425
  }
416
426
  }
417
- function ue(e) {
427
+ function pe(e) {
418
428
  let t = {}, n = [], r, i;
419
429
  for (let a = 0; a < e.length; a++) {
420
430
  let o = e[a];
@@ -439,4 +449,4 @@ function $(e, t) {
439
449
  return Array.isArray(n) ? n : [];
440
450
  }
441
451
  //#endregion
442
- export { U as a, j as c, N as d, b as f, x as h, G as i, M as l, S as m, Z as n, I as o, y as p, W as r, L as s, ae as t, A as u };
452
+ export { W as a, j as c, N as d, b as f, x as h, K as i, M as l, S as m, Z as n, I as o, y as p, G as r, L as s, se as t, A as u };
package/dist/cli.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAmKA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCxD;AAED,wBAAgB,cAAc,IAAI,MAAM,CASvC"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA6LA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCxD;AAED,wBAAgB,cAAc,IAAI,MAAM,CASvC"}
package/dist/cli.js CHANGED
@@ -1,2 +1,2 @@
1
- import { n as e, t } from "./cli-CNlT2O2s.js";
1
+ import { n as e, t } from "./cli-CQCkDA9J.js";
2
2
  export { t as main, e as packageVersion };
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, o as c, p as l, r as u, s as d, t as f, u as p } from "./cli-CNlT2O2s.js";
1
+ import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, o as c, p as l, r as u, s as d, t as f, u as p } from "./cli-CQCkDA9J.js";
2
2
  export { u as createAuthoringPack, r as defaultModuleRoots, c as defaultModulesManifest, d as ensureDefaultModules, l as filamentModulesDir, s as findCatalogEntry, a as formatAuthoringPack, t as installPlugin, o as listPlugins, i as loadCatalog, f as main, p as parseSourceArg, e as parseTypeList, n as removePlugin };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agent-ix/quoin",
3
- "description": "Spec workflow and catalog CLI for Agent IX.",
4
- "version": "0.3.7",
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.4.0",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
@@ -54,7 +54,7 @@
54
54
  "test-results:warnings": "./node_modules/.bin/jest-results warnings"
55
55
  },
56
56
  "dependencies": {
57
- "@agent-ix/ix-cli-core": ">=0.10.4",
57
+ "@agent-ix/ix-cli-core": ">=0.10.5",
58
58
  "@agent-ix/ts-plugin-kit": ">=0.1.3",
59
59
  "yaml": "^2.9.0"
60
60
  },
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: gap-analysis
3
+ description: Verify a targeted plan is complete and validated — every task done, the Test
4
+ Matrix backed by real tracking tags in tests, and code fully traced to spec (flagging
5
+ underspecified code with no owning requirement). Optional semantic review checks that
6
+ intent↔test↔code actually agree. Emits a quire-validated SpecReview artifact to
7
+ reviews/YY-MM-DD-<slug>.md.
8
+ ---
9
+
10
+ # Gap Analysis
11
+
12
+ Use this skill as a **post-implementation verification gate** for one targeted plan.
13
+ It answers three questions and, on request, a fourth:
14
+
15
+ 1. **Is the plan done?** Every `Task` in the targeted plan bundle is `status: done`.
16
+ 2. **Is the Test Matrix real?** Every Test Case in the matrix is backed by an actual test
17
+ carrying a matching **tracking tag** (`TC-xxx`, `FR-xxx-AC-x`) in the test code.
18
+ 3. **Is anything unspecified?** Code/behavior exists with **no owning** StR/US/FR/NFR
19
+ (the reverse, code→spec gap).
20
+ 4. **(optional) Does intent match reality?** For each requirement↔test↔code triple — does
21
+ the test validate the requirement's *intent*, does the test actually exercise the code,
22
+ and does the code match the requirement's intent.
23
+
24
+ The result is a single **quire-validated `SpecReview`** document (`analysis: gap-analysis`)
25
+ written to `reviews/YY-MM-DD-<slug>.md`, with a **Verdict** (PASS / CONDITIONAL / FAIL)
26
+ and a validated **Findings** table.
27
+
28
+ ## When to use
29
+
30
+ - After `implement-plan` (or any implementation effort) to confirm a plan is genuinely
31
+ complete and verified before closing it.
32
+ - To audit drift between spec, tests, and code for an existing component.
33
+ - As a release/merge gate that produces a durable, traceable review artifact.
34
+
35
+ This skill is **read-only over the codebase** — it inspects and reports; it does not fix
36
+ code, edit the plan, or change the matrix. Its only write is the SpecReview artifact.
37
+
38
+ ## Inputs
39
+
40
+ - A target **plan bundle** `plan/<Plan-id>-<slug>/` (the user may name it; otherwise pick).
41
+ - The component **spec** (`spec/spec.md` for `org`/`name`) and **Test Matrix**
42
+ (`spec/matrix.md` or `spec/tests.md`).
43
+ - The **source** and **test** trees of the component.
44
+
45
+ ## Steps
46
+
47
+ 0. **[Target selection](references/step-1-target-selection.md)**: Resolve the plan bundle,
48
+ spec root, Test Matrix, and `org`/`component` for `ix://` URIs.
49
+ 1. **[Plan completion](references/step-2-plan-completion.md)**: Assert every `Task` is
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.
54
+ 3. **[Underspecified code](references/step-4-underspecified-code.md)**: Find code/behavior
55
+ with no owning requirement (reverse gap), plus stubs masquerading as complete.
56
+ 4. **[Semantic review](references/step-5-semantic-review.md)** *(OPTIONAL — ask first)*:
57
+ Judge intent↔test↔code agreement per requirement. Skip unless the user opts in.
58
+ 5. **[SpecReview artifact](references/step-6-specreview-artifact.md)**: Write and validate
59
+ the `SpecReview` to `reviews/YY-MM-DD-<slug>.md`.
60
+
61
+ All steps required except Step 4, which is gated on user choice.
62
+
63
+ ## The optional semantic review
64
+
65
+ Steps 1–3 are mechanical and cheap. Step 4 is an expensive, judgment-heavy LLM pass.
66
+ **Before running it**, ask the user explicitly (e.g. with a yes/no choice):
67
+
68
+ > Run the optional semantic review (intent↔test↔code)? It's slower but verifies that tests
69
+ > actually validate requirement intent and exercise real code.
70
+
71
+ If yes, fan the work out (one subagent per FR or per area) for thoroughness. If no, note in
72
+ the SpecReview's Coverage section that semantic review was skipped.
73
+
74
+ ## Output
75
+
76
+ A `SpecReview` (`spec-artifacts-process` archetype) at `<project_root>/reviews/YY-MM-DD-<slug>.md`:
77
+
78
+ - Frontmatter `type: SpecReview`, `analysis: gap-analysis`, `id: SR-NNN`, `scope`,
79
+ `review_set: subset`, and `relationships:` (`reviews` → the plan, `references` → the matrix).
80
+ - Body: `## Summary`, `## Verdict` (PASS/CONDITIONAL/FAIL), `## Findings`
81
+ (validated table `ID | Severity | Summary | Refs`), `## Coverage` (rollup).
82
+
83
+ > **Note:** `reviews/` is at the **repo root** by deliberate choice for this skill, not
84
+ > `spec/reviews/`. quire validation is path-agnostic, so this is fine.
85
+
86
+ Validate before finishing:
87
+
88
+ ```
89
+ quire validate --scope <project_root> "reviews/**/*.md"
90
+ ```
91
+
92
+ ## Verdict rule
93
+
94
+ - **FAIL** — any incomplete/blocked task, any matrix Test Case with no backing tagged test,
95
+ or any `high`-severity finding.
96
+ - **CONDITIONAL** — only `medium`/`low` findings (e.g. untracked tests, minor drift).
97
+ - **PASS** — no gaps; record the single `FND-001 | low | No gaps found | -` row.
@@ -0,0 +1,53 @@
1
+ # Step 1: Target Selection
2
+
3
+ **Goal**: Resolve exactly what this run audits — one plan bundle, its spec, its Test
4
+ Matrix — and the `ix://` identity used in the output artifact.
5
+
6
+ ## Process
7
+
8
+ ### 1. Resolve the target plan
9
+
10
+ Mirror `spec-to-plan/references/step-0-plan-selection.md`:
11
+
12
+ 1. **Named in context?** If the user passed a plan id (`Plan-002`) or one was established
13
+ earlier this session, use it.
14
+ 2. **Otherwise discover.** Glob `plan/*/plan.md`, read each frontmatter `id`/`title`/`status`,
15
+ and present the list:
16
+
17
+ ```
18
+ Plans available to gap-analyze:
19
+ - Plan-001 electron-hello core app (active)
20
+ - Plan-002 packaging & distribution (active)
21
+ ```
22
+
23
+ Ask which one. One run targets **one** bundle.
24
+
25
+ ### 2. Locate the spec and Test Matrix
26
+
27
+ - **Spec root.** Single-repo: `spec/`. Multi-repo: `specs/<category>/<component>/spec/`.
28
+ - **`org` / `component`.** Read from `spec/spec.md` frontmatter (`org`, `name`). These build
29
+ the `ix://<org>/<component>/<id>` URIs used in the SpecReview `relationships:`.
30
+ - **Test Matrix.** Look for `spec/matrix.md` first, then `spec/tests.md` (both names are in
31
+ use across the ecosystem). Note its frontmatter `id` (e.g. `TestMatrix-001` / `TM-001`)
32
+ for the `references` edge.
33
+ - **Requirements.** Note the requirement files under `spec/functional/`,
34
+ `spec/non-functional/`, `spec/usecase/`, `spec/stakeholder/` — Steps 3 and 4 trace against
35
+ these ids.
36
+ - **Source / test trees.** Identify where implementation and tests live (e.g. `src/` +
37
+ `tests/`, or language-specific layout). Used in Steps 2–4.
38
+
39
+ ### 3. Hand off
40
+
41
+ State explicitly, so later steps and the artifact agree:
42
+
43
+ - target bundle path (e.g. `plan/Plan-002-packaging-distribution/`)
44
+ - spec root, matrix path + id
45
+ - `ix://<org>/<component>` prefix
46
+ - where source and tests live
47
+
48
+ ## Notes
49
+
50
+ - If there is **no** plan bundle, stop and tell the user — gap-analysis audits a plan; it
51
+ does not invent one (use `spec-to-plan` first).
52
+ - If there is **no** Test Matrix, Step 2 a/Plan checks still run, but record a `high`
53
+ finding that the matrix is missing and Step 3 cannot verify coverage.