quality.md 0.2.2 → 0.3.1

package/README.md

@@ -3,6 +3,22 @@
 **QUALITY.md** is an agent-friendly file format and companion agent skill and
 CLI for continuously improving the quality of coding agent and AI assistant projects/harnesses.
 
+## Why QUALITY.md
+
+As software — and the agents that write it — moves faster, quality erodes
+quietly through three accumulating debts:
+
+- **Technical debt** — code drifting from where it should be.
+- **Cognitive debt** — the mounting burden of understanding complex or
+  under-documented systems.
+- **Intent debt** — software diverging from what stakeholders actually need.
+
+QUALITY.md makes a team's quality expectations explicit and checkable, so those
+gaps stay visible and addressable instead of compounding.
+
+> The three-debt framing draws on Margaret-Anne Storey, *The Triple Debt of
+> Software Development* ([arXiv:2603.22106](https://arxiv.org/abs/2603.22106)).
+
 ## Install
 
 1. Install the agent skill:
@@ -66,9 +82,11 @@ ratingScale:
     criterion: "Falls below the minimum acceptable bar."
 targets:
   triage:
+    title: Triage
     source: ./support
     factors:
       responsiveness:
+        title: Responsiveness
         description: Customers receive timely, useful attention.
         requirements:
           "urgent messages are visible":
@@ -76,6 +94,7 @@ targets:
               New messages are classified so urgent customer-impacting issues
               are separated from routine requests.
       accuracy:
+        title: Accuracy
         description: Replies are correct, complete, and grounded in policy.
         requirements:
           "answers cite the current policy":
@@ -122,16 +141,17 @@ but it is where the model explains itself.
 The root model is a target plus a model-wide `ratingScale`.
 
 ```yaml
-title: <string>                 # Recommended
+title: <string>                 # Required
 description: <string>           # Optional
 ratingScale:                    # Required, ordered best to worst
   - level: <level-name>         # Required, unique within the scale
-    title: <string>             # Optional
+    title: <string>             # Required
     description: <string>       # Recommended
     criterion: <string>         # Required
 source: <string>                # Optional
 factors:                        # Optional*
   <factor-name>:
+    title: <string>             # Required
     description: <string>       # Recommended
     factors:                    # Optional
       <sub-factor-name>: <Factor>
@@ -178,31 +198,40 @@ assessment -> findings -> rating result
 ## The CLI
 
 > **The CLI is an early work in progress.** Today the binary ships
-> `qualitymd init`, `qualitymd lint`, `qualitymd spec`, and the
+> `qualitymd init`, `qualitymd lint`, `qualitymd spec`, `qualitymd status`, and the
 > `qualitymd evaluation` run-record surface.
 
-`qualitymd` draws one hard line: the **CLI is deterministic and never calls a
-model.** It scaffolds and validates a `QUALITY.md`, resolves target nodes and
-their `source` manifests, records evaluation artifacts, renders reports, and
-gates CI. The deep, judgment-based evaluation of a subject against its model is
-carried by **skills**, not by any CLI command.
-
-The deterministic surface:
-
-- **`qualitymd init`** — scaffold a starter `QUALITY.md` to fill in.
-- **`qualitymd lint`** — validate a file's structure, fast and deterministic,
-  exiting non-zero on errors so it drops into CI.
-- **`qualitymd spec`** — emit the bundled `QUALITY.md` format specification.
-- **`qualitymd evaluation create-run`** — create and number an evaluation run
-  folder.
-- **`qualitymd evaluation add-record`** — write assessment, analysis, and
-  recommendation records from judgment payloads.
-- **`qualitymd evaluation set-planned-coverage`** — write optional planned
-  assessment and analysis coverage for resume diagnostics.
-- **`qualitymd evaluation show-status`** — inspect whether a run is ready to
-  render.
-- **`qualitymd evaluation build-report`** — derive `report.md` / `report.json`
-  and optionally gate with `--fail-at-or-below`.
+`qualitymd` draws one hard line: the **CLI never asks an AI model to judge your
+project.** It creates and checks `QUALITY.md` files, shows what the file covers,
+writes evaluation records for the `/quality` skill, renders reports, and can
+fail CI when ratings fall below your chosen bar. The judgment work happens in
+the skill, not in the CLI.
+
+### Common commands
+
+| Goal                   | Command                          |
+| ---------------------- | -------------------------------- |
+| Show the format rules  | `qualitymd spec`                 |
+| Create a starter file  | `qualitymd init [path]`          |
+| Check a file           | `qualitymd lint [path]`          |
+| Fix simple lint issues | `qualitymd lint --fix [path]`    |
+| Show project status    | `qualitymd status [path] --json` |
+| Show version info      | `qualitymd version --json`       |
+| Check for updates      | `qualitymd upgrade --check`      |
+| Show command help      | `qualitymd <command> --help`     |
+
+Typical local loop:
+
+```sh
+qualitymd spec
+qualitymd init
+qualitymd lint
+qualitymd status --json
+```
+
+The `/quality` skill uses additional evaluation commands behind the scenes.
+The detailed command guide lives in the bundled
+[`CLI Quick Reference`](skills/quality/resources/cli-quick-reference.md).
 
 ## Conceptual model
 

package/bin/qualitymd.js

@@ -24,7 +24,8 @@ try {
   process.exit(1);
 }
 
-const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+const env = { ...process.env, QUALITYMD_INSTALL_METHOD: "npm" };
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit", env });
 
 if (result.error) {
   throw result.error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quality.md",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Companion CLI for the QUALITY.md file format and /quality agent skill, used to evaluate and improve AI assistant projects and harnesses.",
   "homepage": "https://getquality.md",
   "keywords": [
@@ -34,12 +34,12 @@
     "bin"
   ],
   "optionalDependencies": {
-    "@qualitymd/cli-darwin-arm64": "0.2.2",
-    "@qualitymd/cli-darwin-x64": "0.2.2",
-    "@qualitymd/cli-linux-arm64": "0.2.2",
-    "@qualitymd/cli-linux-x64": "0.2.2",
-    "@qualitymd/cli-win32-arm64": "0.2.2",
-    "@qualitymd/cli-win32-x64": "0.2.2"
+    "@qualitymd/cli-darwin-arm64": "0.3.1",
+    "@qualitymd/cli-darwin-x64": "0.3.1",
+    "@qualitymd/cli-linux-arm64": "0.3.1",
+    "@qualitymd/cli-linux-x64": "0.3.1",
+    "@qualitymd/cli-win32-arm64": "0.3.1",
+    "@qualitymd/cli-win32-x64": "0.3.1"
   },
   "publishConfig": {
     "access": "public"