docs: forbid splicing a new ledger row

[any-victor]

Summary

• Bundled skill and qctl instructions now say: do not splice a new - id:; add/park create rows; there is still no verb to change notes on an existing row.
• Queue QCTL-030 for that missing set verb. add --notes is create-time only.

Test plan

• cargo test --test cli instructions_prints_the_installed_contract_exactly
• cargo test --test cli bundled_skill_names_the_package_version
• cargo run -- check

[kodus-hostinger]

Review

Incremental · 0 open

@kody review after new commits. @kody full re-reads the whole PR.

Summary

What these patches change

Documentation guardrail against hand-editing the ledger

Both agent-facing contracts now carry the same prohibition, so the guidance stays consistent regardless of which surface an agent reads:

• src/instructions.md — the "Mutate" guidance gains an explicit "do not splice a new - id: into the file" clause pointing at add/park as the row-creating verbs, plus a candid admission that no verb covers editing notes or acceptance on an existing row. Since this file is the source of the shipped contract, the existing instructions_prints_the_installed_contract_exactly test asserts the new wording byte-for-byte.
• skills/qctl/SKILL.md — the same rule is repeated in the "Mutate" section, along with a pointer to which flags (--notes, --blocked-by, --plan, --link) replace the fields a hand edit used to set. The frontmatter description also gains a new activation trigger ("Use when adding or parking a ledger row instead of editing tasks.yaml by hand"), which widens skill discovery to the case where an agent is about to reach for the YAML directly rather than only when qctl is mentioned by name.

The rationale given in both places is the same and is a real behavioral difference, not just style: archive also strips the archived id out of every blocked_by that referenced it, so a hand edit silently leaves dangling blockers behind.

Backlog entry for the missing verb

tasks.yaml gains QCTL-030, which converts the documented gap into tracked work rather than leaving it as a permanent caveat. Worth noting from the acceptance criteria, as they constrain the eventual implementation:

• the verb must be a surgical rewrite of only the named fields, preserving the rest of the file — consistent with the formatting-preservation property the other verbs already claim in instructions.md;
• note appending must not clobber the existing scalar, implying set needs append semantics distinct from replace;
• behavior on archived rows must be either a refusal or an explicit documented rule, and an unknown id must fail;
• the docs touched by this PR must be updated again once the verb lands, closing the loop on the "no verb yet" sentences added here.

The notes field records that Document::set already handles top-level scalar patching, so the new verb is framed as extending an existing mechanism to row scope rather than new machinery. It also explicitly rules out two alternatives: a second ledger skill, and blessing a YAML splice.

Release metadata

.changeset/no-splice-id.md marks this as a patch for qctl. Since the bundled skill declares version: 0.4.0 in its frontmatter and a test asserts the skill names the package version, the version bump and the skill file need to stay in sync on release.

Observations

• QCTL-030 is added to queue: with blocked_by: [], so it is immediately startable and does not depend on the doc changes shipping first.
• The changeset copy and the two documentation files state the same rule three times in slightly different wording; the instructions.md text is the one under exact-match test coverage, so future edits to the skill wording will not be caught by that test.

Files

File	Status	+	−
.changeset/no-splice-id.md	added	+5	−0
skills/qctl/SKILL.md	modified	+7	−0
src/instructions.md	modified	+4	−2
tasks.yaml	modified	+12	−0

Open

No open findings.

History

When	Pass	Open
26 Aug 19:52 UTC	Incremental	0

_{Inspect this review}