Level the openDox assembly-root scaffold for the carve (OQ-O) - #3
Merged
Merged
Conversation
Adds the README doc index, records the strict-status-check policy difference between the opendox and openxdox rulesets in docs/branch-protection.md, and declares the carved_from: slot in contracts/manifest.yaml (RULED OQ-I) so the carve PR fills a shape that was written down in advance. No carve content. Lane: openxfactory-4-opendox-extraction Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 2 hours by commenting @sourcery-ai review. Upgrade to get a review now.
Reviewer's GuideLevels the openDox assembly-root scaffold by documenting the future carve provenance slot, adding the required README documentation index, and recording—but deliberately not changing—the branch-protection policy difference; no carve content or pinned scaffold files are modified. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
There was a problem hiding this comment.
🟢 Approval recommended
Only a minor documentation consistency nit was found, with no functional or behavioral changes introduced.
Pull request overview
Levels the openDox assembly-root scaffold ahead of the carve by reserving/documenting the carve provenance schema and documenting the one known branch-protection policy difference, without changing repository behavior or adding carve content.
Changes:
- Add a
## Documentationindex section to the README that linksdocs/content. - Document the
strict_required_status_checks_policydifference (recorded, not changed) indocs/branch-protection.md. - Predeclare (in comments only) the planned top-level
carved_from:mapping shape incontracts/manifest.yaml.
File summaries
| File | Description |
|---|---|
| README.md | Adds a documentation index section/table linking docs/ content. |
| docs/branch-protection.md | Records the measured ruleset policy difference between the opendox and openXdox families. |
| contracts/manifest.yaml | Adds a comment block specifying the future carved_from: provenance mapping shape (no YAML data change). |
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Every posture assertion the levelling pass added now carries an explicit failure message, matching test_required_file_exists, so a red CI names the missing file instead of raising a bare AssertionError. - Family prose names the REPOSITORIES (openDox / openXdox) rather than the lowercase project ids, which are reserved for project.yaml's project: key. - docs/branch-protection.md's opening sentence about ruleset state rephrased. - The manifest comment says why MACHINE-READ is the openXwallet precedent's own word rather than a truncation of machine-readable. No behaviour change; every suite and validator re-run green. Lane: openxfactory-4-opendox-extraction Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
There was a problem hiding this comment.
🟡 Changes recommended
The new provenance comment block currently asserts a docs/opendox-cutover-runbook.md path that does not exist in this repository and should be reworded to avoid a false reference.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 1
- Review effort level: Lite
Contributor
Author
|
Lane: openxfactory-4-opendox-extraction (formerly openxfactory-opendox) INDEPENDENT VERIFICATION of head
FAIL/SHOULD-FIX: the unresolved Copilot thread above (SHOULD-FIX, not blocking — advisory doc wording only). |
brettheap
added a commit
that referenced
this pull request
Sep 16, 2026
…ve) (#9) Lane: openxfactory-4 (openXfactory-4-openDox_extraction) Refs opensoft/openxFactory#656 (stays OPEN). CLAIM: 5699629088. First leg of pin lockstep #3, on lockstep #2's precedent (#8 -> 3819625, LANDED note 5689609863): `code` (opensoft/openDox-code) advances `1e469713` -> `0b4e8bbf`, carrying S 3.4 slice S8 leg B (opensoft/openDox-code#23, LANDED note 5690615323): six pre-carve path constants repaired - test_outline_model.py:22, test_doxbench_view.py:303, test_doxbench_knowledge.py:31, test_doxbench_document_abstract.py:44, test_doxbench_memory_gateway.py:32, test_bullseye_widget.py:1674 - each one the reason a whole arrived suite could not run, and every one of them declared on its own row in openxFactory#1025. That leg's own validate list went 10 files -> 27 and 283 -> 694 tests. RULED 5656343213, "the path constant moves, the file does not". `spec` unchanged at `a8f5eb73`. Two files, the two the lockstep invariant predicts for a leg with no workflow @<sha> reference. The digest is sorted-ls-tree-r-v1 recomputed from the submodule's own object store - 165 entries - and independently re-checked, not retyped. Gate evidence: `validate` run 35112642084 SUCCESS at `c46a352a3ce6a4931ba45fb7480d83938b66d482`; `validate-pins.py` `pins ok` (tree digest recomputed, gitlink/pin-file lockstep confirmed); `validate-manifest.py` and `validate-repository-naming.py` pass. Copilot's review at that head read from the BODY, not the thread count: `5224471846`, "Approval recommended - No unresolved review comments; the dependency pin and metadata are synchronized", files reviewed 2/2, comments generated 0, and NO suppressed-comments section. 0 review threads / 0 unresolved. Lane: openxfactory-4 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
brettheap
added a commit
that referenced
this pull request
Sep 19, 2026
… 3.7 FLOOR PART 3, § 5.4 (d)) and spec to 8fe8c4c7 (four of the five § 6 re-homes) (#10) Lane: openxfactory-4 (openXfactory-4-openDox_extraction) Refs opensoft/openxFactory#656 (stays OPEN). CLAIM: [5738280604](opensoft/openxFactory#656 (comment)). Runbook **Phase 3** — `docs/opendox-cutover-runbook.md`:1812, *"the assembly roots: `carved_from` + gitlink + pin, ONE COMMIT"*. The second and last of the pair; opensoft/openXdox#12 is the first. ## What moves — four paths, no fifth | leg | gitlink + pin `commit:` | `digests.tree_sha256:` | | --- | --- | --- | | `code` | `0b4e8bbf…` → **`d816cf06f1c9752a39c2b71ba40adc4ae3f3bf66`** | `db8817dd…` → **`ac877e49b7ec001a22be21ce18021208e00f9d1d2c2ceb997b060a0b247fbcac`** | | `spec` | `a8f5eb73…` → **`8fe8c4c71c4da8d363394441ad9e2c9547e540a3`** | `658c034d…` → **`f63c5b8fee6bf0fded4cb745555dea6427b274683c5d5bccac01c82e2b0fadbb`** | ``` code | 2 +- contracts/code-pin.yaml | 4 ++-- contracts/spec-pin.yaml | 4 ++-- spec | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) ``` Each target is that repository's `main` tip, **measured at 2026-09-19T01:31Z** and not carried forward. The runbook's pre-push object check (:1825-1830 — *git stores a gitlink without checking the object is present, so a wrong pin commits and pushes clean*): `git -C code cat-file -t d816cf06…` and `git -C spec cat-file -t 8fe8c4c7…` both print `commit`, and both equal `origin/main` in their own repository. ## What the advance carries — the largest of the arc **`code`, nine commits** (64 files, 37 529 insertions, 1 358 deletions): | | | | --- | --- | | `d816cf0` | § 3.6 follow-up #2: a linked worktree's metadata, and a store refusal that is a refusal (openDox-code#32) | | `93ccc3d` | § 3.7 FLOOR PART 3, openDox side: the declared conformance factory and Q-F1's transposition (#31) | | `5c86713` | § 3.6 follow-ups: the seven findings #26 registered, each with its case (#30) | | `373b05a` | § 5.4 FLOOR PART 2 clause (d), openDox leg: the collection triple pinned on the required check (#29) | | `4f8ae01` | § 3.6: openDox creates a repository as a first-class act, with RULING C3's conformant local-git adapter (#26) | | `aca94ec` | § 3.5: the openDox runtime — FastAPI + Postgres, identity and coordination, and nothing else (RULED Q1/Q2) (#25) | | `52b237e` | § 3.4 S7 residue: the display facet threaded to the seven leaves it never reached (#28) | | `5c137a9` | § 3.4 RULED Q7: a contributed binding's CSS leaves `styles.css` for the binding's own sheet (#27) | | `0e65b5f` | the two intent-feed DOM suites retired at this leg (#24) | **`spec`, eight commits** (15 files, 3 636 insertions, 0 deletions): | | | | --- | --- | | `8fe8c4c` | § 6.2 — the surviving `-v2` chat-turn family (openDox-spec#15) | | `66d5977` | § 6.5 — `add-lens-document-selection`, the set-builder half (#14) | | `3b7f80c` | § 6.3 — `add-doxchat-model-intake`, the model plane (#13) | | `edeed08` | § 6.4 — `add-composed-view-authoring`, openDox's first OpenSpec change (#12) | | `54e9107` | Front-end boundary note, amendment #3 (#11) | | `7d12428` | Front-end boundary note, amendment #2 (#10) | | `61866d2` | § 3.4 boundary note: the five rulings Q1–Q5 and the S1–S3 start (#9) | | `a44ac06` | § 3.4 design note: the front-end package boundary (#8) | **Taken with openXdox#12, this pair is the first moment BOTH roots name all five § 6 re-homes:** § 6.1's refresh lane is `openXdox-spec` `f088b097`, pinned by #12; § 6.2–6.5 are `openDox-spec` `8fe8c4c7`, pinned here. ## The third fact-class is VACUOUS here, measured rather than assumed `scripts/validate-pins.py` holds gitlink + pin-file `commit:` + **every** `.github/workflows/*.yml` `<org>/<leg>@<sha>` reference as one invariant. This root has one workflow and exactly one 40-hex `@sha` in it — `actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349` (`validate.yml`:104) — naming neither leg, so there is no third fact to move and no *"workflow @<sha> reference(s) agree"* note is printed. `neutral_product_pins: []` here, so unlike openXdox's root there is no neutral-pin recheck either: **five `ok` lines, not six.** A grep for the two outgoing shas across the whole tree finds them in exactly the two pin files and nowhere else. ## Both digests recomputed, by two independent paths that agree `sorted-ls-tree-r-v1`, via this repository's own `scripts/repo_shape.py` — `tree_digest()` reads the submodule's **object store**, `tree_digest_from_gh()` reads the **forge's** recursive tree listing: ``` code d816cf06f1c9 local=ac877e49b7ec001a22be21ce18021208e00f9d1d2c2ceb997b060a0b247fbcac gh =ac877e49b7ec001a22be21ce18021208e00f9d1d2c2ceb997b060a0b247fbcac AGREE=True spec 8fe8c4c71c4d local=f63c5b8fee6bf0fded4cb745555dea6427b274683c5d5bccac01c82e2b0fadbb gh =f63c5b8fee6bf0fded4cb745555dea6427b274683c5d5bccac01c82e2b0fadbb AGREE=True ``` Neither was retyped from anywhere. ## Verification — BEFORE and AFTER, the same five lines so they compare line for line **BEFORE**, at root `c4c5014d9b39ac55e5df957db23a56db38847a6b`, legs initialized with `git submodule update --init code spec` (never a bare `git add` of a submodule): ``` ok spec: gitlink == contracts/spec-pin.yaml commit a8f5eb73671c ok spec: tree digest recomputes (658c034d6eba…) ok code: gitlink == contracts/code-pin.yaml commit 0b4e8bbf68fa ok code: tree digest recomputes (db8817ddde1a…) ok contracts/shape-pin.yaml: 10 copied shape file(s) match their digests pins ok ``` exit 0. **AFTER**, at this branch's head: ``` ok spec: gitlink == contracts/spec-pin.yaml commit 8fe8c4c71c4d ok spec: tree digest recomputes (f63c5b8fee6b…) ok code: gitlink == contracts/code-pin.yaml commit d816cf06f1c9 ok code: tree digest recomputes (ac877e49b7ec…) ok contracts/shape-pin.yaml: 10 copied shape file(s) match their digests pins ok ``` exit 0. `make validate` — naming + manifest + pins, *what CI runs* — is green end to end: `validate-repository-naming.py` exit 0 (`openDox neutral-product/assembly`, `openDox-spec project-leg/spec`, `openDox-code project-leg/code`), `validate-manifest.py` `manifest ok: openDox (opendox), 3 legs`, `validate-pins.py` `pins ok`. ## Negative control — so the green is not read as vacuous With the gitlink moved and `contracts/code-pin.yaml` left at the old commit in the working tree, the same command exits **1** with two findings: ``` FINDING pin-gitlink-mismatch: code: gitlink d816cf06f1c9752a39c2b71ba40adc4ae3f3bf66 != contracts/code-pin.yaml commit 0b4e8bbf68fabfcd65d4f0d80e619c20a013e888 FINDING pin-digest-mismatch: contracts/code-pin.yaml: digests.tree_sha256 ac877e49b7ec… recomputed at 0b4e8bbf68fa db8817ddde1a… 2 finding(s). THE LOCKSTEP RULE: … ``` Restored from the index and re-verified green. **The arm that has to fire, fires.** ## What deliberately does NOT move `contracts/manifest.yaml` `carved_from` = `{opensoft/openxFactory, b075fd91dc8fced8e1373825ba80220c33536bae}` — the CARVE commit, a provenance record of an event (runbook § 1.1), not a pin that tracks a head; the runbook's item (3) was discharged by the commit that wrote it. Also `contracts/shape-pin.yaml`, `project.yaml`, and every other file. ## The downstream consequence, measured openxFactory pins openDox **directly** (`contracts/opendox-pin.yaml` = `c4c5014d…`, `openDox` gitlink = `c4c5014d…`) and openXdox's root pins it too (`c4c5014d…`). `verify-opendox-pin.py` **check 5** compares those two declarations **to each other**, not to openDox's current head — so this advance breaks nothing: openxFactory continues to pin an older openDox root, which is what a pin is for. **Registered as the follow-up, not taken here:** advancing openxFactory to this new root is a **three-repository** lockstep — openxFactory's `openDox` gitlink, openxFactory's `contracts/opendox-pin.yaml`, and openXdox's `contracts/opendox-pin.yaml` (read as a **blob** at whatever commit openxFactory's `openXdox` gitlink names) must all name the same openDox commit in one landing, or check 5 refuses `opendox-pin-lockstep-mismatch`. ## Sequencing, and what this PR is not This is the Phase 3 **pin** act. § 3.8 (`tasks.md`:1517-1521) and § 4.6 (`tasks.md`:2049-2050) cut `dox-v1.0` / `xdox-v1.0` **in the assembly root**, *"over the commit that names both legs"* — this commit is the first one that names the landed legs. It **cuts nothing**: runbook § 9, Phase 6 (:2000) — *"the tags (§ 3.8 and § 4.6). **BRETT'S ACT, ALWAYS.**"* Sibling search before authoring: `gh pr list --repo opensoft/openDox --state open` returned **zero** open pull requests at 2026-09-19T01:31:12Z. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Lane: openxfactory-4 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Lane: openxfactory-4-opendox-extraction (formerly openxfactory-opendox)
Refs opensoft/openxFactory#656
RULING (Brett Heap,
opensoft/openxFactory#656, 2026-09-09): "OQ-O → level the six scaffolds first, one small PR per repo (docs/,openspec/project.md, strict-check and pytest pins aligned)" — before any carve content, so that a carve failure is never confounded with a scaffold difference. This is one of the six.What this changes
contracts/manifest.yamlcarved_from:slot and its exact shape in a comment block — RULED OQ-I: this file, in each assembly root, is where the carve's machine-read provenance record lands. It is hand-authored and validated by nothing (scripts/validate-manifest.pyreadsproject.yaml, and is digest-pinned bycontracts/shape-pin.yaml), which is precisely why the shape is written down in advance rather than invented at the carve. No key is added; the YAML data is byte-for-byte unchanged.docs/branch-protection.mdREADME.md## Documentationdoc index — the xFactory standing rule that a new doc is linked from the README in the PR that adds it, now level across all six repositoriesThe reference leg
opensoft/openDox-codeis the reference for everything the four legs align on (pinned pytest major,permissions: contents: read). This repository is an assembly root, not a leg: itsvalidateruns the three neutral openRepoShape validators, not pytest, and its.github/workflows/validate.yml,.gitignoreandMakefileare digest-pinned bycontracts/shape-pin.yaml— editing them is drift, so this PR does not touch them.Tests run locally
The shape-pin check passing is the proof that nothing this PR edits is a copied openRepoShape file.
NOT DONE, deliberately
openxFactory docs/opendox-carve-manifest.yamlis placed by this PR. The carve is a later, separate PR under OQ-H (history-preservinggit filter-repo).strict_required_status_checks_policyisfalseon the threeopendoxrulesets andtrueon the threeopenxdoxones. That is a repository setting outside a pull request's reach, and which policy the family standardises on is your call, not an author's. The difference is now written down in everydocs/branch-protection.mdinstead of being discovered.carved_from:value. The two assembly-root PRs declare the SLOT and its shape (RULED OQ-I); the carve PR fills it.Asking for Brett Heap's separate word to land this (CODEOWNERS
* @brettheap; admin merge).🤖 Generated with Claude Code
Summary by Sourcery
Level the openDox assembly-root scaffold by documenting its provenance slot, repository documentation, and known branch-protection difference before the carve.
New Features:
Enhancements:
Documentation: