From a13b9016aba729ba11c2f9379e29d120d9a15aa6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Victor=20Ara=C3=BAjo?= Date: Wed, 26 Aug 2026 16:50:07 -0300 Subject: [PATCH] docs: forbid splicing a new ledger row add and park create rows. There is still no verb to change notes on an existing one; that is QCTL-030, not a YAML splice. --- .changeset/no-splice-id.md | 5 +++++ skills/qctl/SKILL.md | 7 +++++++ src/instructions.md | 6 ++++-- tasks.yaml | 12 ++++++++++++ 4 files changed, 28 insertions(+), 2 deletions(-) create mode 100644 .changeset/no-splice-id.md diff --git a/.changeset/no-splice-id.md b/.changeset/no-splice-id.md new file mode 100644 index 0000000..c334b60 --- /dev/null +++ b/.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. diff --git a/skills/qctl/SKILL.md b/skills/qctl/SKILL.md index 334bc38..3c02951 100644 --- a/skills/qctl/SKILL.md +++ b/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 diff --git a/src/instructions.md b/src/instructions.md index 1d13549..dd92651 100644 --- a/src/instructions.md +++ b/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 diff --git a/tasks.yaml b/tasks.yaml index 51dc8de..aed1881 100644 --- a/tasks.yaml +++ b/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