Ratify realize-doc-health-direction-arc on Brett Heap's word (#656 6023375303)

[brettheap]

Lane: openxfactory-4 (openXfactory-4-openDox_extraction)

Refs #656 (stays OPEN).

THE RATIFICATION RECORD for realize-doc-health-direction-arc (plan 038's T071), the doc_health direction arc's own change. It landed as a draft through #1247 → 51456835 and #1253 → fc4fa0ff. No requirement, decision or task text moves: the change has no spec delta (skip_specs: true). It lands through the holder's lander in a Rule 6 window; this actor merges nothing.

The word

RULED by Brett Heap, 2026-10-06 at about 18:59Z, by interactive multi-choice, verbatim "Ratify it (Recommended)", recorded at #656 comment 6023375303 (created 2026-10-06T19:00:45Z).

The option text he saw read "I post your word on #656 and land the ratification record (Status: ratified, Ratified by) under a Rule 6 window. T072 can start right away; T074 and T075 then follow in order."

The form followed

cd494e4c / #1151, "Ratify add-neutral-product-standalone-operability on Brett Heap's word (#656 5815412869)", file for file and field for field. The holder's ruling at #656 6023619783 confirms the one choice that differs from the change's as-filed text (below).

What is ratified, and what the word authorizes

• Ratified: the change as landed on main at fc4fa0ff (T070b: fold Copilot's four items into realize-doc-health-direction-arc before the ratify word (plan 038) #1253, merged 2026-10-06T18:56:42Z). Its change-directory tree, 02d362f6ebcaf49e18aa107f7ce2b3a409ca2275, is identical at T070b: fold Copilot's four items into realize-doc-health-direction-arc before the ratify word (plan 038) #1253's final head e4f3f1db and on current main, and the last commit on main that touches it is fc4fa0ff. Copilot's review at e4f3f1db read "Approval recommended", Findings: None.
• D1–D7 stand as recommended. tasks.md 1.2 provides that the word rules design.md § 11's D1–D7 as recommended unless it says otherwise, and the word does not. The record says that this applies 1.2's own rule and does not claim Brett Heap was shown the seven one by one.
• Authorized: per the ruling record, the realization in plan 038's order: T072 (opportunistic, ARC-6), then T074 and T075. None of it happens by the word itself.
• Nothing archives or promotes. The change stays ACTIVE until its realization is merged and green, and it gates neither release 2's close nor File add-neutral-product-standalone-operability: open the BUILD arc, recording ten rulings #1144's archive (ARC-Q3 (a)).

What this PR changes

Six files. None of the changes is requirement or scenario text.

openspec/changes/realize-doc-health-direction-arc/proposal.md

• Status: ratified, with a Ratified: citation.
• A qualifier above the filing's "DRAFT. FILING IS NOT RATIFYING" paragraph, which is kept verbatim as the filing's record.
• A ## Ratification record section.
• A read-at-ratification note after the D1–D7 list.

design.md and tasks.md

• Status: ratified, with a Ratified by: citation. This is the citation split File add-neutral-product-standalone-operability: open the BUILD arc, recording ten rulings #1144's record carried.
• design.md § 11: the same read-at-ratification note.
• tasks.md 1.1 (the filing, citing T070: file realize-doc-health-direction-arc, the doc_health direction arc's own change (plan 038) #1247 → 51456835 and T070b: fold Copilot's four items into realize-doc-health-direction-arc before the ratify word (plan 038) #1253 → fc4fa0ff) and 1.2 (this act) are ticked. Boxes go from 0 [x] / 23 [ ] to 2 [x] / 21 [ ].
• 1.2 keeps its as-filed wording and gains a marked italic note on the one divergence (below), as Ratify add-neutral-product-standalone-operability on Brett Heap's word (#656 5815412869) #1151 did for its own 1.8.

.openspec.yaml

• approved_by / approved_on are ADDED after proposed_on. kind, id, path, reason, proposed_by and proposed_on do not move.

New record: review/ratification-2026-10-06.md (Status: ratified, Kind: report, one Ratified: citation).

README.md: the Active changes entry's status, now linking the record.

The sequenced-after ledger row does not move.

The one divergence from the text as filed. tasks.md 1.2 says the record carries Status: record. It carries Status: ratified with a Ratified: citation, as #1144's record did. document-lifecycle sanctions both spellings, the option put to Brett read "(Status: ratified, Ratified by)", and a Status: record file trips record-immutability (CRITICAL) on any later edit, such as a Copilot fix commit on this PR. Confirmed by the holder at #656 6023619783.

Gate state at f9f71063

The tree is main at 40d6e5c1 plus this PR's twelve commits (the change itself, five merges of main and six re-measurements of the record), with the submodules initialised. After the first head, main moved five times: the archive of add-worker-input-budget (#1258), then #1266 and #1264, then the archive of amend-worker-input-budget-dispatch-wording (#1269), then #1263, #1270, #1271 and #1267 (renew-resolved-council-protocol), then #1272, #1275 (the archive of correct-naming-families-count) and #1277 (a bot review-lane repin). They touch README.md, docs/, the sweep ledger, other changes, the review-lane contracts and workflows and the doc-health and project-repo-schema specs, and not the change directory (its tree is still 02d362f6ebcaf49e18aa107f7ce2b3a409ca2275 on main, last commit fc4fa0ff). So main was merged in, never rebased, and everything below was re-measured. main has since moved again, to b4b9d903 (a new change, refresh-install-repository-enumerations-opsxfactory-gateway: its own directory, a README entry and a ledger row). It is not merged here, per the holder's one-merge instruction, and a trial merge with it is clean.

OPENSPEC_TELEMETRY=0 openspec validate realize-doc-health-direction-arc --strict → valid (the pinned 1.12.0)
validate-openspec-cli-pin.py --all --strict   → exit 0, 0 UNDISPOSITIONED failures
                                                113 passed, 1 failed (114 items); the 1 = the accepted exception, as on main alone
validate-code-surface.py . / validate-target-release.py .  → passed
validate-sequenced-after.py . / --ledger-diff → pass; ledger consistent (235 rows), this row unmoved
proposal-support.py . verify realize-doc-health-direction-arc → ok
doc-health.py --single-repo .                 → 31 critical, 26 error, 69 warning, 19 info
                                                report byte-identical to main alone (same clone kind); 0 findings name this change
doc-health families (1.2's falsifier)         → proposal-origin 0 findings, status-validity 0 findings
                                                (negative control: dropping proposal.md's Ratified: line takes ratified-provenance 27 → 28 critical, naming proposal.md)
pytest -m "not postgres" -k "ledger or records or sequenced or openspec"  → 615 passed, 3 skipped
pytest sequenced_after code_surface target_release proposal-support scope_globs packet_reference → 866 passed, 311 subtests passed
pytest tests/doc-health                       → 2157 passed

An earlier tests/doc-health run showed 8 failures in test_neutrality_dispatch.py. They were this actor's own environment, not the tree: an exported REPO variable collided with the fake scout worker's REPO. With it unset the file gives 25 passed, and the whole directory is green above.

Copilot

• First head 0039a47e: review 5436306140, "Approval recommended", Findings: None, 0 threads.
• Head 739da6e0 (after the first merge of main): review 5440756736, "Approval recommended", Findings: None, 0 threads.
• Head 69479c77 (after the second merge of main): review 5459920482, "Approval recommended", 0 threads.
• Head 83e3511e (after the third merge of main): review 5460937374, "Approval recommended", 0 open findings, 0 threads.
• Head b186eb62 (after the fourth merge of main): review 5462168108, "Needs a closer look", 0 open findings, 0 threads. Its stated reason is that final approval depends on human validation of the governance authority and the historical provenance assertions. The holder ruled at openDox + openXdox: two open-source layers, an installable app with users, projects and a database; domain descendants pin openXdox (Brett's ruling 2026-09-04) #656 6069024568, item 5, that this is NOT a block, because that authority is Brett Heap's ratify word 6023375303.
• Checks at b186eb62: the rollup was SUCCESS with 15 status checks, all SUCCESS, including merge-master-approval, pytest-suite and SonarCloud Code Analysis. 0 threads unresolved.
• Head f89fc853 (after the fifth merge of main): review 5464071466, "Needs a closer look", 0 open findings, 0 threads. Its stated reason is that the exact-head checks and the Codex review were then pending, and that final approval also depends on governance provenance, which the holder's ruling at openDox + openXdox: two open-source layers, an installable app with users, projects and a database; domain descendants pin openXdox (Brett's ruling 2026-09-04) #656 6069024568, item 5, covers.
• Final head f9f71063 (a record-only correction of the corpus subtest figure, 312 to 311, which the completed run measured): Copilot requested through the reviewer API after the push. Its result, the checks and the thread count are recorded here once the exact final head has been reviewed.

Codex

• At b186eb62, @codex review was posted twice (comments 6067925769 and 6069046343), and the chatgpt-codex-connector[bot] answered both with the usage-limit message (comments 6067927988 and 6069048581). No Codex review existed at that head.
• At f89fc853, @codex review (comment 6071059884) was answered with a review: Reviewed commit f89fc853cb, "Didn't find any major issues" (comment 6071083487; summary comment 6071062721, Code Review completed at 2026-10-08T23:29:24Z).
• At the final head f9f71063, @codex review was posted once after the push (comment 6071252263). The bot's reply is recorded here once it arrives. READY needs a Codex "Reviewed commit" at the exact head, or Brett Heap's explicit waiver (openDox + openXdox: two open-source layers, an installable app with users, projects and a database; domain descendants pin openXdox (Brett's ruling 2026-09-04) #656 6069024568, item 4).

What is NOT done

• No code, pin, gitlink, contract bundle or release tag moves. T072, T074 and T075 are the realization, and none of them starts by this PR.
• Plan 038's specs/038-…/tasks.md is not edited here. T071's tick there goes in the holder's own bookkeeping batch.
• Nothing archives or promotes.

Rule 6: this PR touches openspec/changes/ and the README OpenSpec Records block, so it lands in a declared window by the holder, and not by this actor.

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

This PR ratifies the existing realize-doc-health-direction-arc OpenSpec change against the exact fc4fa0ff baseline, records Brett Heap’s ruling and D1–D7 interpretation, authorizes but does not perform T072/T074/T075, and updates lifecycle metadata and documentation without changing requirements, scenarios, code, sequencing, or release state.

Sequence diagram for ratifying the doc-health direction arc

sequenceDiagram
    actor BrettHeap
    participant Issue656
    participant RatificationPR
    participant OpenSpecChange
    participant Plan038

    BrettHeap->>Issue656: post ratify word
    RatificationPR->>OpenSpecChange: record Status: ratified and approval citations
    RatificationPR->>OpenSpecChange: add ratification record
    RatificationPR->>OpenSpecChange: preserve fc4fa0ff baseline
    RatificationPR->>Plan038: authorize T072
    RatificationPR->>Plan038: authorize T074 after T072
    RatificationPR->>Plan038: authorize T075 after T074
    Note over RatificationPR,Plan038: No realization, archive, promotion, or release change

Loading

Flow diagram for ratification lifecycle and realization authorization

flowchart TD
    A[Change landed at fc4fa0ff] --> B["Brett Heap posts Ratify it (Recommended)"]
    B --> C[Record ratification and update lifecycle metadata]
    C --> D[Status: ratified; D1-D7 stand as recommended]
    D --> E[T072: opportunistic realization]
    E --> F[T074: follow in plan order]
    F --> G[T075: follow in plan order]
    C --> H[Change remains ACTIVE]
    H --> I[Archive only after realization is merged and green]

Loading

File-Level Changes

Change	Details	Files
Record Brett Heap’s ratification of the already-landed OpenSpec change and its authorized realization scope.	Mark the proposal, design, and tasks documents as ratified with citations to the ruling and record. Add the ratification record documenting the baseline commit, D1–D7 interpretation, authorized task order, and explicit non-effects. Add approval metadata while preserving drafting provenance and record the intentional Status: ratified deviation from the filed task wording. Update the README active-change entry to link the ratification record and reflect ratified status.	openspec/changes/realize-doc-health-direction-arc/proposal.md openspec/changes/realize-doc-health-direction-arc/design.md openspec/changes/realize-doc-health-direction-arc/tasks.md openspec/changes/realize-doc-health-direction-arc/.openspec.yaml openspec/changes/realize-doc-health-direction-arc/review/ratification-2026-10-06.md README.md
Preserve the change’s implementation and lifecycle boundaries while documenting validation of the ratification packet.	Keep skip_specs, declarations, sequencing ledger, and realization tasks unchanged; no code, pin, gitlink, release, archive, or promotion changes are introduced. Document validation, doc-health, proposal-support, sequencing, and test results, including the accepted baseline exception and environment-specific test issue.	openspec/changes/realize-doc-health-direction-arc/review/ratification-2026-10-06.md openspec/changes/realize-doc-health-direction-arc/.openspec.yaml openspec/changes/realize-doc-health-direction-arc/tasks.md

---

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 documentation consistently reflects the verified ruling and preserves the intended lifecycle and implementation boundaries.

Review effort: Balanced
Findings: None

What changed in this PR

Ratifies the doc-health direction arc without changing implementation scope.

Changes:

• Records Brett Heap’s ratification and approval provenance.
• Updates lifecycle statuses, task completion, and the README index.
• Adds the formal ratification report.

File	Description
README.md	Marks the change ratified.
proposal.md	Adds ratification status and record.
design.md	Records D1–D7 as accepted.
tasks.md	Completes filing and ratification tasks.
.openspec.yaml	Adds approval provenance.
review/​ratification-2026-10-06.md	Captures the ruling and authorization boundaries.

---

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

[Copilot]

Copilot review overview

🟢 Approval recommended

The lifecycle metadata and ratification provenance are consistent, with no unresolved review findings.

Review effort: Balanced
Findings: None

[Copilot]

🟢 Approval recommended

The documentation-only changes consistently reflect the cited ruling and established ratification precedent.

0 open findings

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

The ratification record, cited ruling, lifecycle metadata, and first ratifying commit are consistent, with no unresolved findings.

0 open findings

🧠 Review effort: Balanced

[brettheap]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[Copilot]

🔵 Needs a closer look

Final approval depends on human validation of governance authority and historical provenance assertions.

0 open findings

🧠 Review effort: Balanced

[brettheap]

@codex review

[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 22 hours and 57 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[brettheap]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-08T23:46:11.398776Z	f9f7106	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: f89fc853cb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🔵 Needs a closer look

Exact-head checks and the required Codex review remain pending, while final approval also depends on governance provenance.

0 open findings

🧠 Review effort: Balanced

[brettheap]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: f9f71063bd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🟢 Approval recommended

The ruling’s author, scope, timestamp, and exact baseline were verified, with no unresolved review defects.

0 open findings

🧠 Review effort: Balanced

[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-4 (openXfactory-4-openDox_extraction)

READY at f9f7106 — holder, on Brett's word "land #1261 when green" (2026-10-09 ~01:03Z).

• At the head f9f71063: 15 checks SUCCESS and 1 SKIPPED. Copilot "Approval recommended". Codex reviewed f9f71063bd. 0 unresolved threads.
• Since the head's CI, main has moved to 564f565a (Archive refresh-install-repository-enumerations-opsxfactory-gateway: the sixth install repository promoted into the three enumerations; Purpose widened #1278, lane 5's archive). The squash lands the same tree as merging main into the branch, and T071 verified that merged tree locally: MERGED-TREE-GREEN: local merge 0ad0fa52 (not pushed), clean; validate-openspec-cli-pin.py --all --strict exits 0 with 0 UNDISPOSITIONED; the pinned openspec validate realize-doc-health-direction-arc --strict is valid; code-surface, target-release, sequenced-after (incl. --ledger-diff, 236 rows) and proposal-support verify pass; doc-health is byte-identical to pristine main 564f565a, and its negative control fires; pytest: the ledger, records, sequenced and openspec subset 615 passed, 3 skipped; the corpus directories 866 passed with 312 subtests.
• Lands in a Rule 6 window (squash), through the holder's openxFactory lander.
• Authority: Brett's ratify word 6023375303; plan 038 RULED 6013547504; "land Ratify realize-doc-health-direction-arc on Brett Heap's word (#656 6023375303) #1261 when green".

[brettheap]

Lane: openxfactory-4 (openXfactory-4-openDox_extraction)

LANDING — lane openxfactory-4, session faabad8b-8c31-4958-abd5-b35bdc9cd282@Eagle, 2026-10-09T01:13:29Z, PR #1261 into opensoft/openxFactory main

[brettheap]

Lane: openxfactory-4 (openXfactory-4-openDox_extraction)

LANDED — lane openxfactory-4, 2026-10-09T01:13:48Z, PR #1261 → a020b34 (opensoft/openxFactory main; squash)