[jonahgabriel]

OMN-16606 — omnibase_core is README-only; the doc gate is now strict

Wave 4 of the org-wide documentation consolidation (epic OMN-16602). This repo carries 199 markdown files outside the kb-doc-gate allowed set on dev; after this PR it carries zero, and .kb-doc-gate.yaml is mode: strict so it stays that way.

The migrated content is already live in the knowledge bases — both KB PRs merged before this one, per the companions-merge-first rule:

Destination	PR	Merged	Merge commit
Public knowledge-base	#70	2026-09-02T14:45:12Z	c90fcdce
Private knowledge-base-internal	#91	2026-09-02T14:34:02Z	7cf4abb6

So this PR deletes originals whose content is already published, not content that would be lost.

Disposition of all 199

• 113 to the public knowledge base (feat: v0.1.1 improvements - type safety, introspection, and documentation #70): 40 architecture records, 53 guides, 20 reference pages — platform architecture, the node-building and mixin-development tutorial series, node templates, conventions, and the generated api/ surface. Public routing was applied only to self-hoster documentation carrying no internal topology, credentials, customer, or people content.
• 37 to the internal knowledge base (chore(deps): bump pypdf from 6.1.3 to 6.4.0 #91): per-repo architecture handshakes, the in-flight mixin/handler/protocol migration guides, repo tooling and CI-operations docs, and the eight validator generation-provenance records.
• 47 deleted: 23 pointer stubs left by earlier waves (a stub is documentation that still exists — the 2026-09-01 ruling on OMN-16602 says delete it and let the README carry the pointer role), 4 dated audit/evidence records, 5 .onex_state/ working artifacts, 6 section index READMEs, docs/INDEX.md, a self-declared HISTORICAL deprecation note, an explicitly-not-implemented CI proposal, and near-empty directory notes.
• 2 moved: CONTRIBUTING.md and CODE_OF_CONDUCT.md to .github/, where GitHub also reads them and where the gate's allowed set covers them.

References fixed in the same change

README.md gains a Documentation section naming the knowledge base as the single home (16 KB links). CLAUDE.md's doc map and inline links repointed. .github/CONTRIBUTING.md, SECURITY.md and CHANGELOG.md links repointed — onex-validate-links passes (9 files, 53 links, 0 broken). .github/CODEOWNERS, .github/workflows/ci.yml, .pre-commit-config.yaml, .importlinter, mypy.ini, architecture-handshakes/check-policy-gate.sh and architecture-handshakes/validator-requirements-baseline.yaml repointed. The eight generated validators' docstrings cite the provenance record in the knowledge base. .secrets.baseline pruned of the 7 entries whose files no longer exist.

Three local gates narrowed, none bypassed

Each because the deletion exposed a matcher that was too broad, and each is documented in the commit body:

• validate-no-empty-directories: a directory that groups sub-collections and holds no direct files is not incomplete refactoring. docs/assets, docs/evidence and the two demo corpus trees were only non-violating because a signpost README sat in them. Excluded by name alongside the existing src and drift entries, which exist for exactly this reason.
• no-untracked-todos and check-stub-implementations: the todo-marker validator's own source names TODO/FIXME/HACK as its subject and already carries this repo's file-level escape hatch (onex-allow-file-todo-marker, OMN-13480), which neither hook reads. Both hooks now skip that one package.
• yamlfmt no longer rewrites .kb-doc-gate.yaml: the gate reads it with a deliberately stdlib-only parser accepting a restricted YAML subset.

No bypass flags of any kind were used: no --no-verify, no PREPUSH_FULL_SUITE, no ENABLE_SMART_TESTS=off, no PREPUSH_ALLOW_*, no core.hooksPath, no pre-push override grant, no skip tokens, and no edit to the pre-push host table or any timeout budget.

Second commit: the guard-job contract re-pin

tests/unit/validation/test_ci_workflow_shape.py pins a SHA-256 over the canonical JSON of every audited guard job. The doc repoint above changed one GITHUB_STEP_SUMMARY echo inside core-infra-boundary — it named docs/decisions/ADR-005-core-infra-dependency-boundary.md, a file this branch deletes, so the old line linked to nothing. The second commit re-pins that digest 403fa52e -> a6fa1e4f after auditing the readable workflow diff, which is the procedure the module itself prescribes. runs-on, if, continue-on-error, permissions, needs, strategy, container, timeout-minutes and the executed validation command are all unchanged, so the digest records a documentation repoint, not a weakened gate. That module is 77 passed in 19.72s on the rebased head.

Rebase onto current dev, and what that fixed

This branch was cut at d07d6c46 and is rebased onto d191ffb2, which now carries three pre-push fixes that did not exist when it was first pushed:

• OMN-16634 (feat(OMN-16634): add the hcloud EC2 overflow row and make the host-identity refusal proofs host-independent #1640) — the host-identity refusal proofs are now host-independent. Before it, tests/scripts/test_prepush_hook_host_identity_guard.py asserted an IDENTITY refusal and got a CAPACITY refusal on every lab host except this Mac. The first governed escalation for this branch's earlier head (h101, 4h48m04s) returned 8 failed / 44,640 passed / 59 skipped; three of those eight were exactly that test, in a file this branch does not touch. That class of false RED is gone from dev.
• OMN-17603 (fix(OMN-17603): carry the pytest execution policy across the pre-push remote dispatch seam (3:36:06 -> 1:32:51 on h105) #1643) — the remote leg now carries -n4, --timeout=60 and --reruns=2 across the dispatch seam. Previously tests/pytest.ini shadowed the pyproject addopts on argv tests/, so every off-box core escalation silently lost the reruns, and one of the three failures above died on the test's own 180s subprocess budget under a single-threaded run.
• OMN-17602 — h101/h105 moved from one slot to two and the hcloud row was added, so a core lane no longer serialises on one slot per host.

One rebase conflict, in .secrets.baseline, resolved by content rather than by side: dev had added three Hex High Entropy String entries for docs/evidence/prepush-hcloud/hcloud-host-identity.receipt.json (a file this branch keeps — the scrub targets prose, not JSON evidence), while this branch had removed the whole surrounding docs block. Keeping the branch side wholesale would have dropped a live file's entries and made detect-secrets-hook report them as NEW. The resolution keeps that one block and drops the six for deleted files. Verified mechanically: every remaining baseline key resolves to a file in git ls-files (0 stale), and the key delta against origin/dev is exactly {docs/demo/BETA_DEMO_GUIDE.md, docs/guides/CONTRACT_PATCHING_GUIDE.md, docs/guides/PROTOCOL_UUID_MIGRATION.md, docs/guides/replay/REPLAY_SAFETY_INTEGRATION.md, docs/patterns/CONFIGURATION_MANAGEMENT.md, examples/contracts/SECURITY.md, scripts/validation/README.md} removed, nothing added.

Third commit (056550d3): what the scrub broke, and what it exposed

Three CI reds on the first push, all diagnosed from job logs, none waited out.
Two were real defects the deletion caused or uncovered; one needed no code.

Check architecture handshake — a genuine over-deletion, now reverted.
Exit 2, Source handshake not found in omnibase_core: architecture-handshakes/repos/omnibase_core.md.
architecture-handshakes/repos/*.md are not prose: check-handshake.sh reads
source_sha256: out of a repo's installed .claude/architecture-handshake.md
and compares it to the sha256 of the matching file under repos/. Verified on
this branch rather than asserted — .claude/architecture-handshake.md carries
source_sha256: 3553cfd0922697c12358831f9ad7a2f0c032794772de0c2e88185b547c7fa52a
and shasum -a 256 architecture-handshakes/repos/omnibase_core.md returns
exactly that digest; bash architecture-handshakes/check-handshake.sh . now
returns OK: Handshake for 'omnibase_core' is current, rc=0. omnibase_core IS
the fleet source of truth for these, and omnibase_infra / omnibase_spi /
omniclaude / omnimemory each check this repo out and run the same script
against these paths — they survive today only because they pin an old core SHA,
so the deletion would have broken each at its next repin. That is ruling (2) of
the 2026-09-01 OMN-16602 comment verbatim: markdown a program loads as
executable configuration stays. The 8 contracts are restored and
.kb-doc-gate.yaml gains the one glob covering them, with the sha256 binding
recorded in the config comment. The 301-line architecture-handshakes/README.md
that accompanied them IS prose and stays deleted.

Contract Compliance Check — a pre-existing CI defect this PR's size
exposed, fixed. Exit 1, and it takes the required CI Summary down with it
(default-deny sweep failures: Contract Compliance Check). Its "Classify
dependency-bot workflow-only PR" step ran gh pr diff <n> --name-only, which
fetches the whole unified diff before filtering to names, so GitHub answered
HTTP 406: Sorry, the diff exceeded the maximum number of lines (20000) /
PullRequest.diff too_large. Nothing about this PR's content failed — its size
did, and the same red lands on any large PR in this repo. Replaced with the
files API, proven live on this very PR: the old verb still returns HTTP 406,
gh api repos/OmniNode-ai/omnibase_core/pulls/1644/files --paginate --jq '.[].filename' returns all 230 filenames. The API caps at 3000 files;
truncation can only shrink the list, workflow_only requires ALL entries under
.github/workflows/ and bool(files) guards empty, so a truncated or empty
response leaves exempt=false and the full compliance check runs — fail-closed
in both directions. test_ci_workflow_shape.py is 77/77 after the edit.

The kb-doc-gate pins had drifted, and adding the config entry above exposed
it. .pre-commit-config.yaml pinned omniclaude 82a3394c; the required
kb-doc-gate / kb-doc-gate check resolves its validator at 3e6d14da. Those
two parsers disagree on the config schema itself — 82a3394c reads
exemptions: and exits 2 on allowed:; 3e6d14da reads allowed: and
rejects exemptions: — so ANY per-repo entry is a guaranteed local-vs-CI
disagreement. Their default sets differ besides: 82a3394c allows
**/tests/**, **/rules/**, **/hooks/**, **/CONTRIBUTING.md and
**/CODE_OF_CONDUCT.md anywhere, which 3e6d14da narrows to the three
tests/**/{fixtures,data,golden}/** subtrees and root-anchored .github/
placement. The strict end state this PR establishes is defined by the stricter,
CI-resolved validator, so the local pin is advanced to match it — one line in
each file, in one PR, per the gate's own doctrine.

No code needed for the third red. The 25 occ-preflight / eligibility
failures, plus Canonical Inference Gate, receipt-honesty and
call-reject-skip-token / occ-preflight / eligibility, were one defect and an
ordering artifact: occ-preflight ran at 11:11:58Z reporting "PR body is missing
required 'Evidence-Source:' line", and the occ-autobind bot stamped
Evidence-Source: OCC#8186 into the body seconds later. The other three
self-report occ-preflight result was failure; refusing to run <name>. All four
are green on the current head.

Governed pre-push: three attempts, one red, and it was the machine not the code

Attempt 1 (head d839c27c), h105 slot 1, ratio 0.179: 44683 passed, 59 skipped, 3 xpassed in 5698.79s (1:34:58), REMOTE_WRAPPER_EXIT=0.

Attempt 2 (head 056550d3) found no fit lab slot at pick time and ran the
escalation LOCALLY on the 24-core h200 while peer lanes held load1 at 42–86.
It went RED: 8 failed, 44711 passed, 53 skipped, 3 xpassed in 15141.01s (4:12:21). All 8 are wall-clock assertions in files this branch does not
touch — six test_parity_replay.py::test_exit_reasons_are_distinguished[...]
subprocess cases hitting Failed: Timeout (>60.0s) from pytest-timeout,
test_registry_hook_performance.py::test_execution_scales_linearly
("500/100 ratio 22.3 suggests non-linear scaling"), and
test_antipattern_checker.py::test_runs_in_under_five_seconds ("Checker took
5.8s (limit: 5s)"). Proven artifacts, not defects: those three files re-run in
isolation at load1 43 give 46 passed in 57.80s, rc=0. No override was minted,
no host table or timeout budget was edited, and the RED was not argued past —
the push simply waited for lab capacity.

Attempt 3 (same head 056550d3), pushed into a measured window (h105 one slot
free at load1 1.78/10, h101 both free at 2.20/12) and placed on h105 slot 1,
ratio 0.173, mode authorizing. Probe trail: h200=busy(heavy_pids=11) h201=busy(lock=1 held=2) h101=fit(0.238) h101.2=fit(0.238) h105=fit(0.173) h105.2=busy(...) hcloud=slot-unknown. Result 44683 passed, 59 skipped, 3 xpassed, 151 warnings in 5759.89s (1:35:59), REMOTE_WRAPPER_EXIT=0, run dir
/Users/Shared/onex-prepush/runs/omnibase_core-056550d34091-12620, suite log
sha256 5ac19a11a1b8ba8db8aad838e148b492ce7a4ec86e4890e25f110da16504e311.
Identical pass/skip/xpass counts to attempt 1 on a different head — which is
itself the evidence that attempt 2's eight reds carried no information about
this change.

dod_evidence

• Gate, strict, on the rebased head: python3 omniclaude/scripts/kb_doc_gate.py --mode strict --repo-root . -> kb-doc-gate: OK (strict mode, 9 tracked markdown file(s) inspected), exit 0. The 9 survivors are all allowed-set: README.md, CLAUDE.md, .claude/architecture-handshake.md, CHANGELOG.md, SECURITY.md, .github/{CONTRIBUTING,CODE_OF_CONDUCT,PULL_REQUEST_TEMPLATE}.md, tests/fixtures/README.md.
• Baseline it replaces, re-measured against d191ffb2 today, not read off a prior report: the same validator run against the canonical dev clone reports kb-doc-gate: FAILED (strict mode) — 199 violation(s), exit 1. git ls-tree -r --name-only origin/dev | grep -cE '\.(md|rst|adoc)$' -> 206; on this branch git ls-files | grep -cE '\.(md|rst|adoc)$' -> 9.
• The required kb-doc-gate / kb-doc-gate check runs on this PR in strict mode (the file's own mode: wins over the caller's input), so a green check here is live proof the end state holds, not an assertion about it.
• README pointer: git show HEAD:README.md | grep -ciE 'knowledge-base|knowledge base|kb\.omninode' -> 16 (origin/dev: 0).
• Both KB PRs verified MERGED via gh pr view, with the merge commits in the table above, before this PR was opened.
• Local gates on the rebased head: uv run ruff format src/ tests/ -> 6335 files left unchanged; uv run ruff check --fix src/ tests/ -> All checks passed!; uv run mypy src/omnibase_core (CI's exact command, .github/workflows/ci.yml lint job) -> Success: no issues found in 4289 source files; pre-commit run --all-files green; tests/unit/validation/test_ci_workflow_shape.py 77/77.
• Governed pre-push, green on the first attempt with zero capacity refusals: scripts/hooks/prepush_smart_tests.sh escalated to the fail-closed full suite (selection: is_full_suite=True reason=shared_module paths=[ tests/ ]) and placed it on h105 (omnibook), slot 1, ratio 0.179, mode authorizing. Probe trail on the record: h200=busy(queue=0 heavy_pids=7 lock=1 held=1 slot=1) h201=fit(0.223,authorizing) h101=busy(...) h101.2=busy(...) h105=fit(0.179,authorizing) h105.2=busy(...) hcloud=slot-unknown. Result 44683 passed, 59 skipped, 3 xpassed, 151 warnings in 5698.79s (1:34:58), REMOTE_WRAPPER_EXIT=0, run dir /Users/Shared/onex-prepush/runs/omnibase_core-d839c27cb88a-83571, suite log sha256 7c34fecf36e88d872dfd8976fd988b56e28e78e317394f364cba2e98bcb82a20. The verdict is host-side and bound to head_sha + argv_sha per OMN-16688. argv.txt on that host reads tests/ -n4 --dist=loadgroup --timeout=60 --timeout-method=signal — the OMN-17603 policy this branch is rebased onto, live. No narrowing was hand-typed and no escalation was bypassed.

Ticket: OMN-16606. Epic: OMN-16602. Gate build: OMN-16589. Gate rollout to this repo: OMN-17172 (#1639, which put kb-doc-gate / kb-doc-gate into dev branch protection in diff mode — this PR flips the repo's own config to strict).

Evidence-Ticket: OMN-16606
Evidence-Source: OCC#8186