Propose and ratify amend-worker-input-budget-dispatch-wording on Brett Heap's word 'ratify 1262 when ready'

[brettheap]

Lane: openxfactory-1

Drafts and RATIFIES the OpenSpec change amend-worker-input-budget-dispatch-wording, the amendment #1262 asks for. Refs #1262.

Ratified in place, as drafted, on Brett Heap's word "ratify 1262 when ready". No requirement or scenario text moved at ratification: the spec delta is blob eead8960 at every commit of this PR. The archive is a separate act on its own word.

The words

Brett Heap, verbatim, in session on 2026-10-07. Each is a RULED line on the lane register (opensoft/brett-wip, lanes/log/openxfactory-1.md) except the second, which the issue itself records.

1. "(a) land as ratified, amend later". His ruling on Copilot's comment 4202036546 at Archive add-worker-input-budget: promote the bounded worker input budget onto doc-health #1258. RULED at 2026-10-07T09:42:21Z (commit 98b8b3d4).
2. "log the issue to change this". The lane filed doc-health canon: 'Bounded worker input budget' calls a forbidden over-budget dispatch conformant; reword the rationale clause #1262.
3. "draft the amendment change for 1262". This PR.
4. "ratify 1262 when ready". RULED at 2026-10-07T09:58:32Z (commit f6964352). Its condition held at 5b3edf14: every required check green, pytest-suite included, and Copilot's review 5441182701 recommending approval with one low-severity citation fix, taken in 5d236d7d. The ratification is commit 3a7ba60c.
5. "yes, land it when green". RULED at 2026-10-07T10:04:03Z (commit 43e9a5c2). This PR lands by SQUASH, by the lane's coordinator, inside a Rule 6 window. The squash commit is then the ratifying commit on main, and it carries the origin's approval pair. Closing doc-health canon: 'Bounded worker input budget' calls a forbidden over-budget dispatch conformant; reword the rationale clause #1262 still needs its own word, and the archive is a separate later pull request.

What changes

One ## MODIFIED requirement in doc-health, Bounded worker input budget. Only the last sentence of its second paragraph is replaced.

As promoted (canon on main 16779816, lines 4083-4087):

Where the WORKER assembles the prompt from a dispatchable unit the orchestrator prepared, the orchestrator SHALL measure each unit's assembled size, record it, and SHALL NOT dispatch a unit it has measured over the budget — dispatching one and letting the worker refuse is conformant but useless, because the same unit is selected again next run.

As amended (#1262's text, verbatim):

Where the WORKER assembles the prompt from a dispatchable unit the orchestrator prepared, the orchestrator SHALL measure each unit's assembled size, record it, and SHALL NOT dispatch a unit it has measured over the budget. The worker's refusal of an over-budget input (scenario "A worker receives an input over the budget") is a backstop that keeps such an input from reaching the model. It does not make an over-budget dispatch conformant, and relying on it wastes the run, because the same unit is selected again next run.

diff of canon's block (openspec/specs/doc-health/spec.md:4070 to the end, 52 lines) against the delta's block gives one hunk:

17,18c17,21
< measured over the budget — dispatching one and letting the worker refuse is
< conformant but useless, because the same unit is selected again next run.
---
> measured over the budget. The worker's refusal of an over-budget input
> (scenario "A worker receives an input over the budget") is a backstop that
> keeps such an input from reaching the model. It does not make an
> over-budget dispatch conformant, and relying on it wastes the run, because
> the same unit is selected again next run.

The title, the first and third paragraphs and all six scenarios (16 bullets) are byte-identical to canon. The archived delta under openspec/changes/archive/2026-10-06-add-worker-input-budget/ is history and is not edited.

Task 1.1: the realization never dispatches over budget (CONFIRMED)

#1262's acceptance 1, checked read-only:

• scripts/doc_health/catalog_dispatch.py at Bound the bounded workers' input to the model's context window #1137's merge 9da52e31:
  • :513-515 measures each shard's assembled input in bytes;
  • :516-517 adds the shard to the dispatch list only when it is <= input_budget_bytes;
  • :527-528 writes shards.json from that list alone;
  • :535-543 records the rest as shards_over_budget.
• On main 16779816, the gate is at :521-522 and the write at :532-533.
• The worker reads only that list. opensoft/xFactory .github/workflows/doc-health-cataloger-worker.yml:171-175 takes ids[0] of shards.json and exits 0 when the list is empty. The file is identical at b2479b6e (xFactory#481) and at main.
• tests/doc-health/test_semantic_input_budget.py:503, test_a_shard_measured_over_the_budget_is_never_dispatched, asserts that the over-budget shard is not dispatched.

So the amended sentence describes behaviour that already holds, and code_surface: none is measured, not assumed.

The ratification (commit 3a7ba60c)

Following #1250's pattern (3cec62fd), in one commit, so the ratifying commit also carries the approval pair:

• proposal.md: Status: draft becomes Status: ratified, with one Ratified: line citing the word, the RULED line and the record;
• tasks.md: Status: ratified with a Ratified by: line; boxes 0.1 and 0.2 ticked with the word;
• .openspec.yaml: approved_by (Brett Heap, the word verbatim) and approved_on: 2026-10-07 ADDED after the drafting pair. Every existing field is unchanged, checked by parsing both versions;
• review/ratification-2026-10-07.md: the record (Status: ratified, Kind: report, Decision date:, Ratifier:, one Ratified: citation and the ratified baseline);
• README.md: the Active changes entry in its ratified form, ending RATIFICATION ONLY.

Not moved: specs/doc-health/spec.md, the ledger row and the self-gate row.

Files

• openspec/changes/amend-worker-input-budget-dispatch-wording/:
  • .openspec.yaml: an ad_hoc origin written by proposal-support.py declare-adhoc with the drafting pair, the approval pair added at ratification, and a related: list;
  • proposal.md, tasks.md, review/ratification-2026-10-07.md;
  • specs/doc-health/spec.md, the one delta.
• README.md: the Active changes entry.
• tests/doc-health/test_modified_block_currency_self_gate.py: one _LEDGER_SUBJECTS row, with its docstring count and chronology. The carriage arm reports this block once, at INFO (1 of 25 units uncarried, which is the amended sentence). A **Removed from canon by** marker was not used, because the marker would be promoted into canon and carry the old sentence with it, which doc-health canon: 'Bounded worker input budget' calls a forbidden over-budget dispatch conformant; reword the rationale clause #1262's acceptance 3 forbids.
• tests/sequenced_after/corpus-ledger.yaml: the seeded row (--moved-by '#1264').

Registered and not taken (tasks.md § 5): a code comment at scripts/doc_health/catalog_dispatch.py:527-528 and a test docstring at tests/doc-health/test_semantic_input_budget.py:506-508 still echo the old clause. Editing them would give a wording packet a code surface.

Review

Copilot reviewed each head this PR asked it to:

• 5441182701 at 5b3edf14: approval recommended, with one low-severity citation fix (r4205972528), taken in 5d236d7d.
• 5441515765 at 3a7ba60c, the ratifying commit: three non-normative record fixes (r4206239376, r4206239452, r4206239504), taken in e9c63a18. None touched requirement or scenario text; the spec delta is still blob eead8960 and .openspec.yaml is unchanged.
• 5441560962 at e9c63a18: approval recommended, no findings.
• 5441620162 at a2761b1f, this head (after the merge of main below): approval recommended, no findings.

Every review thread is answered and resolved: 4 threads, 0 unresolved.

main then moved to a38585e9 (#1266, correct-naming-families-count), and this branch took it by merge commit a2761b1f, never a rebase. The only conflict was the head of the README Active changes list, where both entries are kept, this packet's first, with no byte of either entry changed.

Gates

Same-kind full clones named openxFactory.

At this head, a2761b1f, against main a38585e9:

gate	main a38585e9	this head
validate-openspec-cli-pin.py --all --strict	exit 0; 113 passed, 1 failed (the accepted add-chain-attestation exception), 0 undispositioned	exit 0; 114 passed, the same 1 accepted exception
validate-openspec-cli-pin.py --change amend-worker-input-budget-dispatch-wording	n/a (exit 2, no such change)	exit 0; 1 passed
proposal-support.py . verify amend-worker-input-budget-dispatch-wording	exit 0	exit 0
validate-code-surface.py, validate-target-release.py, validate-scope-globs.py	exit 0	exit 0
validate-sequenced-after.py .	exit 0 (47 active, 19 declaring)	exit 0 (48 active, 20 declaring)
validate-sequenced-after.py . --ledger-diff	exit 0 (233 rows)	exit 0 (234 rows)
validate-former-id-arrival.py, validate-release-tag-gate.py	exit 0	exit 0
doc-health.py --single-repo .	31 critical, 22 error, 69 warning, 19 info	31 critical, 22 error, 69 warning, 20 info. The one added finding is this block's carriage-ledger INFO, named by the self-gate row. No other line moves: no ratified-provenance or proposal-origin finding names the ratified packet
pytest: tests/sequenced_after, tests/proposal-support, the self-gate module and test_semantic_input_budget.py		537 passed

Earlier, against main 16779816, the same validator and doc-health rows held at 24b7862b (draft), 5b3edf14 (ledger seeded), 3a7ba60c (ratified) and e9c63a18. At 24b7862b the pytest subset (tests/doc-health, sequenced_after and nine more gate modules) and the whole suite (--continue-on-collection-errors) failed exactly the same ids as main (7 and 237, from the clone's uninitialized openDox and openXdox legs) plus the 4 sequenced_after ledger tests that fail until the row is seeded; at 5b3edf14, with the row seeded, those modules passed (337 tests). CI's pytest-suite runs the whole suite with the legs. It was green at 5b3edf14, and gh pr checks reports it at this head.

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

This draft OpenSpec change amends one contradictory rationale sentence in the promoted “Bounded worker input budget” requirement, explicitly distinguishing the worker’s refusal backstop from the orchestrator’s prohibition on over-budget dispatches. It is documentation and bookkeeping only: existing scenarios, archived history, and runtime code remain unchanged, while the draft lifecycle and self-gate registration are added.

Flow diagram for the worker input budget wording amendment

flowchart LR
    PromotedRequirement[Promoted requirement contains contradictory rationale]
    DraftAmendment[Draft amendment clarifies SHALL NOT dispatch over-budget input]
    Ratification[Authoring lane ratifies amended wording]
    Canon[Amended wording is archived into canon]

    PromotedRequirement --> DraftAmendment
    DraftAmendment --> Ratification
    Ratification --> Canon

Loading

File-Level Changes

Change	Details	Files
Adds a draft OpenSpec amendment that resolves the contradiction in the bounded worker input budget requirement.	Introduces proposal metadata, rationale, provenance, sequencing, and draft lifecycle tasks for issue doc-health canon: 'Bounded worker input budget' calls a forbidden over-budget dispatch conformant; reword the rationale clause #1262. Adds a ## MODIFIED copy of the doc-health requirement with only the rationale sentence replaced by the issue’s wording. Clarifies that worker refusal is a safety backstop, not permission for the orchestrator to dispatch an over-budget unit. Preserves the existing normative SHALL NOT, all six scenarios, and the archived historical delta. Documents that runtime behavior already avoids dispatching measured-over-budget units, so no code surface is changed.	openspec/changes/amend-worker-input-budget-dispatch-wording/.openspec.yaml openspec/changes/amend-worker-input-budget-dispatch-wording/proposal.md openspec/changes/amend-worker-input-budget-dispatch-wording/specs/doc-health/spec.md openspec/changes/amend-worker-input-budget-dispatch-wording/tasks.md
Registers the draft change in repository bookkeeping and the modified-block self-gate.	Adds the amendment to the README Active changes list with draft status and provenance. Adds a self-gate ledger subject for the intentionally reworded requirement and updates expected finding counts and explanatory assertions. Leaves the sweep-ledger row and ratification/archive tasks pending as required for the draft lifecycle.	README.md tests/doc-health/test_modified_block_currency_self_gate.py

Possibly linked issues

• doc-health canon: 'Bounded worker input budget' calls a forbidden over-budget dispatch conformant; reword the rationale clause #1262: The PR directly implements issue doc-health canon: 'Bounded worker input budget' calls a forbidden over-budget dispatch conformant; reword the rationale clause #1262 by drafting its exact wording amendment and preserving all scenarios.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

Copilot review overview

🟢 Approval recommended

The amendment matches #1262, preserves all scenarios, and aligns with existing dispatch behavior; only a non-blocking citation typo remains.

Review effort: Balanced
Findings: 1

Open (1)

• Fix malformed file-and-line citation · New

What changed in this PR

Drafts the #1262 OpenSpec amendment clarifying that over-budget dispatch is non-conformant while worker refusal remains a backstop.

Changes:

• Adds the single-requirement amendment packet.
• Registers lifecycle and sequencing metadata.
• Updates self-gate expectations for the intentional wording difference.

File	Description
.openspec.yaml	Records origin and related changes.
proposal.md	Explains the amendment and impact.
tasks.md	Tracks verification, ratification, and archival work.
specs/​doc-health/​spec.md	Rewords the contradictory rationale.
README.md	Adds the active draft record.
corpus-ledger.yaml	Registers sequencing metadata.
test_modified_block_currency_self_gate.py	Names the expected informational finding.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

The proposal and task records contain stale lifecycle statements and an incomplete changed-file inventory.

Review effort: Balanced
Findings: 3

Open (3)

• Update code_surface inventory to include ratification report · New
• Align lifecycle wording with completed ratification · New
• Limit archive blockers to unchecked tasks 3.5 and 4.1 · New

Resolved since last review (1)

• Fix malformed file-and-line citation

[Copilot]

Copilot review overview

🟢 Approval recommended

The amendment matches issue #1262, preserves the remaining requirement verbatim, and its governance records are consistent.

Review effort: Balanced
Findings: None

Resolved since last review (3)

• Limit archive blockers to unchecked tasks 3.5 and 4.1
• Align lifecycle wording with completed ratification
• Update code_surface inventory to include ratification report

[Copilot]

Copilot review overview

🟢 Approval recommended

The amendment matches the governing issue, preserves unchanged specification content, and keeps lifecycle records consistent.

Review effort: Balanced
Findings: None

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[brettheap]

Lane: openxfactory-1

LANDING — lane openxfactory-1, session eb835de4-d46e-4bb7-86f3-82780be6f51e@Eagle, 2026-10-08T16:15:41Z, PR #1264 into opensoft/openxFactory main (Rule 6 window; rule6 scan CLEAR; gate PASS at head a2761b1 on main a38585e). On Brett Heap's word verbatim: "yes, land it when green".

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 4 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[brettheap]

Lane: openxfactory-1

LANDED — lane openxfactory-1, 2026-10-08T16:16:15Z, PR #1264 → a936e53 (squash commit into opensoft/openxFactory main). Window closed.