deferred-reads: anchor deferrals on workflow files and cover contract skills #98

New issue

Closed

opened 2026-08-10 14:48:48 +00:00 by john · 1 comment

john commented

2026-08-10 14:48:48 +00:00

Owner

Unblocker for the v2.6.2 context-weight work. Nothing else in this milestone that moves a block behind a Read can land guarded until this ships.

Problem

lib/deferred-reads.mjs (self-verify check 13) is what keeps a deferral honest: delete one Read sentence and the reference becomes unreachable with nothing failing. It has two coverage holes, and every deferral this milestone proposes falls into one of them.

1. It can only anchor on a command SKILL.md with numbered steps. deferredReadIssues() only opens skills/<name>/SKILL.md, and regionLabels() only labels regions under a top-level ^N. step inside <process>. But:

workflow files use <step name="..."> tags and are themselves the @-include
skills/cad-execute/SKILL.md is a bare @-include with no numbered steps
skills/cad-verify/SKILL.md's <process> is the single line "Execute end-to-end."

So a register row for a deferral made from a workflow file can never satisfy its anchor. Adding one fails CI forever; omitting one leaves the deferral unwatched.

2. Contract skills are explicitly out of scope (lib/deferred-reads.mjs:40-44). The stated reason is that dispatch prose "bytes never touch the main thread at all" — that prices main-thread residency and does not price subagent context. A contract byte is paid on every dispatch of that role, which makes it the most multiplied byte in the repo.

Change

Give register rows a file field naming where the Read sentence must live, so a row can point at a workflow file rather than assuming its skill.
Teach regionLabels() to label <step name="..."> regions alongside ^N. numbered steps.
Drop the contract-skill scope exclusion and rewrite the header rationale, which is the one stale claim in it.

Must not regress

The matching unit stays the SENTENCE, not the blank-line block. That bound is load-bearing and the header explains why: skills/cad-land/SKILL.md step 4b is a single ~2,900 B paragraph, so a block-level test passes when the real instruction is deleted, and do NOT Read <path> passes a block-level test.

Likewise, do not consolidate per-arm Read sentences anywhere as part of this. "Each arm's own sentence" is a rule the header documents as reproduced, not theorised.

Acceptance

A register row can anchor a deferral whose Read sentence lives in a cadence-core/workflows/*.md <step name="..."> region, and fails when that sentence is deleted.
A register row can anchor a deferral inside a skills/cad-*-contract/SKILL.md, same failure behaviour.
Existing rows still pass unchanged.
node cadence-core/bin/self-verify.mjs returns ok:true.

Unblocker for the v2.6.2 context-weight work. Nothing else in this milestone that moves a block behind a `Read` can land guarded until this ships. ## Problem `lib/deferred-reads.mjs` (self-verify check 13) is what keeps a deferral honest: delete one `Read` sentence and the reference becomes unreachable with nothing failing. It has two coverage holes, and every deferral this milestone proposes falls into one of them. **1. It can only anchor on a command SKILL.md with numbered steps.** `deferredReadIssues()` only opens `skills/<name>/SKILL.md`, and `regionLabels()` only labels regions under a top-level `^N. ` step inside `<process>`. But: - workflow files use `<step name="...">` tags and are themselves the `@`-include - `skills/cad-execute/SKILL.md` is a bare `@`-include with no numbered steps - `skills/cad-verify/SKILL.md`'s `<process>` is the single line "Execute end-to-end." So a register row for a deferral made from a workflow file can never satisfy its anchor. Adding one fails CI forever; omitting one leaves the deferral unwatched. **2. Contract skills are explicitly out of scope** (`lib/deferred-reads.mjs:40-44`). The stated reason is that dispatch prose "bytes never touch the main thread at all" — that prices main-thread residency and does not price subagent context. A contract byte is paid on every dispatch of that role, which makes it the most multiplied byte in the repo. ## Change - Give register rows a `file` field naming where the `Read` sentence must live, so a row can point at a workflow file rather than assuming its skill. - Teach `regionLabels()` to label `<step name="...">` regions alongside `^N. ` numbered steps. - Drop the contract-skill scope exclusion and rewrite the header rationale, which is the one stale claim in it. ## Must not regress The matching unit stays the SENTENCE, not the blank-line block. That bound is load-bearing and the header explains why: `skills/cad-land/SKILL.md` step 4b is a single ~2,900 B paragraph, so a block-level test passes when the real instruction is deleted, and `do NOT Read <path>` passes a block-level test. Likewise, do not consolidate per-arm `Read` sentences anywhere as part of this. "Each arm's own sentence" is a rule the header documents as reproduced, not theorised. ## Acceptance - A register row can anchor a deferral whose `Read` sentence lives in a `cadence-core/workflows/*.md` `<step name="...">` region, and fails when that sentence is deleted. - A register row can anchor a deferral inside a `skills/cad-*-contract/SKILL.md`, same failure behaviour. - Existing rows still pass unchanged. - `node cadence-core/bin/self-verify.mjs` returns `ok:true`.

john added this to the v2.6.2 milestone

2026-08-10 14:48:48 +00:00

john commented

2026-08-12 15:10:38 +00:00

Author

Owner

Shipped: lib/deferred-reads.mjs anchors workflow-file regions and covers contract skills; the main-thread-only rationale is retired in its header. Verified against the live tree.

Shipped: lib/deferred-reads.mjs anchors workflow-file <step> regions and covers contract skills; the main-thread-only rationale is retired in its header. Verified against the live tree.

john closed this issue

2026-08-12 15:10:39 +00:00