docs: forbid splicing a new ledger row

.changeset/no-splice-id.md

@@ -0,0 +1,5 @@
+---
+qctl: patch
+---
+
+Tell agents not to splice a new `- id:` into `tasks.yaml`. `add` and `park` create rows; the other verbs still beat a hand edit because `archive` also clears `blocked_by`. State that notes and acceptance on an existing row have no verb yet.

skills/qctl/SKILL.md

@@ -5,6 +5,7 @@ description: >-
   park, promote, show, and instructions. Use when a repository has tasks.yaml, prefix QCTL
   or another qctl prefix, mise run q, horizon research/evaluation rows, or
   the user mentions qctl, the work queue, or replacing Ajv test:ledger.
+  Use when adding or parking a ledger row instead of editing tasks.yaml by hand.
   Do not use the vault ompex/task-ledger plugin.
 license: MIT
 version: 0.4.0
@@ -54,6 +55,12 @@ resolved. Do not start a horizon id.
 
 ## Mutate
 
+Do not splice a new `- id:` into `tasks.yaml`. `add` and `park` create rows;
+`--notes`, `--blocked-by`, `--plan`, and `--link` fill fields a hand edit
+used to. Prefer every other verb over a YAML edit: `archive` also takes the
+archived id out of every `blocked_by` that named it. There is no verb yet to
+change notes or acceptance on an existing row.
+
 ```sh
 qctl add -t 'Title' -s repo -o 'Done when…' -a 'Acceptance'
 qctl add -t 'Title' -s repo -o 'Done when…' -a 'Acceptance' --notes 'Why' --blocked-by QCTL-001 --after QCTL-001

src/instructions.md

@@ -134,9 +134,11 @@ YAML: quote list items that start with `#` or contain `: `.
 
 `add` / `start` / `archive` / `park` / `promote` change only the lines they
 must, so a comment, a blank line, a folded scalar and an inline list all
-survive a verb. Prefer the verb over a hand edit: `archive` also takes the
+survive a verb. Do not splice a new `- id:` into the file: `add` and `park`
+create rows. Prefer the verb over a hand edit: `archive` also takes the
 archived id out of every `blocked_by` that named it, which a hand edit
-forgets.
+forgets. There is no verb yet to change notes or acceptance on an existing
+row.
 
 ## Stop conditions
 

tasks.yaml

@@ -157,6 +157,18 @@ queue:
       it the best thing in verctl's documentation. Distinct from QCTL-018,
       which is about the catalog declaring a second qctl pin.
 
+  - id: QCTL-030
+    title: Let a verb update fields on an existing row
+    scope: qctl
+    outcome: Notes, acceptance, title, scope, outcome, plan, and links on a queued or horizon row can be changed without splicing YAML.
+    blocked_by: []
+    acceptance:
+      - qctl set ID rewrites only the named fields on that row and leaves the rest of the file untouched.
+      - Appending notes does not replace the existing scalar.
+      - A missing id fails; archived rows are refused or have an explicit rule.
+      - instructions and the bundled skill name the verb.
+    notes: 'Operator, 2026-08-26: how do we just update metadata on an existing task? add --notes is create-time only. Do not cover this with a second ledger skill or a blessed YAML splice. Document::set already patches a top-level scalar; the verb needs the same surgical rewrite on a row.'
+
 horizon:
   - id: QCTL-019
     title: Resolve a foreign blocker instead of only recording it