feat: adopt unified ctl presentation

.changeset/unified-presentation.md

@@ -0,0 +1,5 @@
+---
+qctl: minor
+---
+
+Route every command through ctl-core's typed App and semantic Document presentation. Add shared pretty, colorless, JSON, quiet, stream, and error behavior; `status --format json` exposes ledger state and `check --format json` exposes its problem array.

.ctl/ver.yaml

@@ -18,18 +18,25 @@ assets:
   linux-x64: {}
 
 # tasks/q/q and examples/mise.toml are served from .ctl/templates, so they need
-# no entry here: a rendered file cannot drift. README is written by hand, so its
-# two version spellings are declared instead — named once, listed by the file
-# that carries them, and both too few and too many stop the release.
+# no entry here: a rendered file cannot drift. README and the bundled skill are
+# written by hand, so their version spellings are declared instead — named once,
+# listed by the file that carries them, and both too few and too many stop the
+# release.
 patterns:
   catalog:
     match: "qctl.git//tasks/q?ref=v{version}"
     occurrences: once
   install:
     match: "github:victor-software-house/qctl@{version}"
     occurrences: once
+  skill:
+    match: "version: {version}"
+    occurrences: once
 
 pins:
   - file: README.md
     package: qctl
     patterns: [catalog, install]
+  - file: skills/qctl/SKILL.md
+    package: qctl
+    patterns: [skill]

AGENTS.md

@@ -23,10 +23,10 @@ Rust policy CLI for in-repo `tasks.yaml` work queues.
   directory every ctl CLI shares, and qctl's own project config will land
   beside it as `.ctl/q.yaml`. There is no `verctl.toml`.
 - Served files — `tasks/q/q` and `examples/mise.toml` — are rendered from
-  `.ctl/templates/`, and README's `?ref=` and install line are declared under
-  `patterns` in `.ctl/ver.yaml` (QCTL-009). Edit the template or the pattern,
-  never the rendered file; the Version PR rewrites all five sites onto the
-  commit the tag names. A template git does not track renders nowhere.
+  `.ctl/templates/`. README's `?ref=` and install line plus the bundled skill's
+  `version:` are declared under `patterns` in `.ctl/ver.yaml` (QCTL-009,
+  QCTL-022). Edit the template or the pattern, never the rendered file; the
+  Version PR rewrites every site onto the commit the tag names. A template git does not track renders nowhere.
   The `q` task's `#USAGE mount` line is `ctl_core::mount_line("q")`.
   Put it in the template. Do not copy it onto `tasks/q/q` while that
   file still pins a release that lacks `--usage-spec`. The Version PR
@@ -53,3 +53,13 @@ test fixtures and assertions.
 
 - `qctl check` does not skip a git trailer scan that failed. A scratch
   ledger that is not in the current repository needs `--no-git`.
+
+## Ownership and Design
+
+- `src/cli.rs` is the Clap grammar. `src/report.rs` owns serializable command
+  results. Domain modules return those results and never print.
+- `src/presentation.rs` maps reports onto ctl-core semantic documents. ctl-core
+  alone owns help, pretty/colorless/JSON emission, stream selection, quiet
+  behavior, terminal width, styling, and tables.
+- `-f` remains qctl's ledger-file shorthand. The root composes ctl-core
+  `FormatLong` with `ColorLong`, so shared `--format` never takes `-f` back.

Cargo.toml

@@ -27,7 +27,7 @@ pedantic = { level = "deny", priority = -1 }
 [dependencies]
 anyhow = "1.0.100"
 clap = { version = "4.6.6", features = ["derive", "env"] }
-ctl-core = { version = "0.1.1", default-features = false, features = ["usage"] }
+ctl-core = { version = "=0.4.2", default-features = false, features = ["app", "usage"] }
 garde = { version = "0.23.0", features = ["derive", "regex"] }
 indoc = "2.0.7"
 jsonschema = { version = "0.49.9", default-features = false }

README.md

@@ -8,9 +8,16 @@
 Control in-repo YAML work queues. One file, one active task, file order is
 priority. Replaces copied Ajv `test:ledger` scripts.
 
+Every command returns typed data through ctl-core. Human output is pretty by
+default; `--color never` or `--no-color` keeps the same layout without ANSI,
+`--format json` emits the report as one JSON line, and `--quiet` suppresses
+successful human output only. `-f` remains the ledger-file shorthand.
+
 ```sh
 mise run q check
 mise run q status
+mise run q status --format json
+mise run q check --format json
 mise run q add -t 'Title' -s repo -o 'Done when…' -a 'Acceptance'
 mise run q start OMX-001
 mise run q archive OMX-001 -e 'Shipped.'

docs/adoption-report.md

@@ -138,7 +138,10 @@ Filed as **QCTL-028**.
 `status` and `check` are read by agents far more often than by humans, and
 parsing a table is fine until the format shifts.
 
-Filed as **QCTL-029**.
+Resolved by the unified ctl-core presentation migration: `--format json`
+serializes the same typed report as pretty/colorless output. Status includes the
+ledger state; check includes its complete problems array and keeps failure exit
+semantics.
 
 ## One ask that was declined
 

skills/qctl/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   the user mentions qctl, the work queue, or replacing Ajv test:ledger.
   Do not use the vault ompex/task-ledger plugin.
 license: MIT
+version: 0.3.1
 compatibility: Requires a qctl binary. A repository-mounted mise `q` task may provision an exact version after a GitHub Release exists.
 ---
 
@@ -33,6 +34,14 @@ mise run q check --no-git
 mise run q instructions
 ```
 
+## Read output
+
+Human output is pretty by default. Use `--color never` or `--no-color` for the
+same layout without ANSI. Use `--format json` for one typed JSON report on
+stdout; `status` includes the ledger state, and `check` carries a `problems`
+array and exits non-zero when it is not empty. `--quiet` suppresses successful
+human output only. `-f` remains `--file`; format has no short `-f`.
+
 ## Three lists
 
 - **queue** — short-term. File order is priority. `active` is `queue[0]` or `null`.