Skip to content

Commit 9b50973

Browse files
luisleo526claude
andcommitted
Docs: the guards bind, because the pages they guard are clean (R5 int12, documentation wave)
The three documentation lanes are cherry-picked above this commit. Each one passed its own gates on its own base; this is what the union of the three needs, and nothing else. The guards go binding. `--strict-docs` was L14-A's ruling that a guard may report rather than fail while the drift it names is exactly what the next two lanes exist to remove. Those lanes have landed: the anchor checker reports bad=0 on every page and the lint 0 offenders, so the flag is removed rather than flipped -- a guard that can be asked not to bind is decoration. The advisory *mechanism* stays in `ci_preflight.py`, with its self-test, for the next guard that lands before its drift is gone; no stage uses it today. `CONTRIBUTING.md` joins both guards' globs: L14-B rewrote it whole and checked it by hand, and nothing kept it true. The anchors. L14-C's 528 header comment lines moved 307 of the anchors in L14-B's rewritten `pine-to-native.md`, which is what happens when two lanes branch from the same tip and one of them edits the headers the other cites. `--fix` re-anchored 277 of them; the remaining 30 are symbols the checker refuses to guess at (`side` on eight lines, `Cancel` on two). Each was resolved by mapping its line through the 7485a40a..HEAD diff of the header it cites and reading both texts: all 30 old lines survive verbatim, so the coordinate moved and the claim did not. Two of the 30 differ from the checker's first candidate -- `cancel_where` is the `NativeRequestField` overload, not the one-argument one, and `FromOwnerFill::ticks` is the flag, not `TrailTicks::ticks`. The two page anchors `native-engine.md` links to, `{#pine_to_native_map}` and `{#pine_to_native_map_trades}`, were dropped by L14-B's rewrite (it split the one "Concept map" section into ten). Restored as `@anchor` commands so that L14-B's per-section ids are kept as well. Doxygen builds at 0 warnings over all inputs, not only over the guarded set. Four references from L14-B's pages pointed at files outside `INPUT`. The front doors are now published -- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `LEGAL.md`, `SECURITY.md` -- and the two engineering records they also named are cited by path instead, because `docs/README.md` states that split and a record is not a page. The lint's last offender was its own false positive: `Series<T>::operator[](k)` inside a code span reads as a markdown link to a file named `k`. An inline code span is not a link, for the same reason L14-A ruled that a fenced block is not a citation; only the span's content is masked, so a real link whose label is code is still read. Two self-tests, one each way. The fourteen other offenders name their epoch correctly -- historical baselines, frozen providers, and P2c's `lifecycle_v2` removal epoch, which is forward, not stale -- so each carries the `<!-- verified HEAD -->` marker the rule provides. P2c landed on main after all three lanes branched, so the migration page still offered the deprecated spelling as the primary one: its `risk_free_rate` row now names `sharpe_monthly` / `sortino_monthly` and records `sharpe_tv` / `sortino_tv` as the deprecated aliases of the same two doubles, with the serialized report key unchanged. ADR-0001 keeps both sections whole -- P2c's "Deprecated public spellings" table and L14-C's rewritten feature-gate rulings -- which `check_kernel_residuals.py` (109 archive hits against 119 ruled identifiers and 11 ruled texts, 0 findings) and `check_native_feature_rulings.py` both still parse. The floors, recomputed on this tree under lane Q12's ran-rows rule: `KERNEL_MIN_TESTS` 189 -> 193 (194 registered, the WebSocket row still skips) and `RELEASE_MIN_TESTS` 554 -> 558. Both +4, the same four rows: L14-A's `test_doc_anchors` and `test_doc_lint`, and L14-B's two example hosts. Cross-lane corrections the union tree still needed: `native-engine.md`'s "all thirteen sources" is fifteen (L14-B added two examples), `docs/ci.md`'s "three guards" is four and its "ten native examples" fifteen, and the kernel row floor the page quotes is the recomputed one. The three L14-C flagged in L14-B's pages -- README's opt-in sentence and `index.md`'s two counts -- were already true here: L14-B's later commits fixed them after L14-C read them. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent a4f5bed commit 9b50973

18 files changed

Lines changed: 355 additions & 301 deletions

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -139,15 +139,15 @@ What each gate refuses:
139139
| `check_adapter_spec_shadowing.py` | the adapter setting a kernel field it is ruled not to set |
140140
| `check_twin_parity.py` | a frozen test assertion rewritten instead of a behaviour change being argued |
141141
| `check_doc_anchors.py` | a `file:line` citation that no longer points at the symbol it claims |
142-
| `check_doc_lint.py` | a stale epoch, a roadmap label or a "there is no … yet" claim the tree has falsified |
142+
| `check_doc_lint.py` | a stale epoch, a roadmap label or a "there is no … yet" claim the tree has falsified | <!-- verified HEAD -->
143143
| `check_pine_to_native_coverage.py` | a Pine builtin with no row on the migration page |
144144
| the CTest row **floors** | a test row that vanished from a profile |
145145

146146
### The floors
147147

148148
`ci_verify.py` counts the CTest rows that actually **ran** and fails below a
149-
floor — `KERNEL_MIN_TESTS` ci_verify.py:88 and `RELEASE_MIN_TESTS`
150-
ci_verify.py:107.
149+
floor — `KERNEL_MIN_TESTS` ci_verify.py:93 and `RELEASE_MIN_TESTS`
150+
ci_verify.py:116.
151151
A deleted or silently skipped row is a failure, not a quieter run. If your
152152
change adds rows, raise the floor in the same commit and say by how much; if it
153153
legitimately removes one, lower it deliberately and say why. `--min-tests`
@@ -184,7 +184,7 @@ python3 scripts/corpus_trades_identity.py --update
184184

185185
The subset runs as a required check on a pull request; the full sweep runs
186186
nightly and on demand. The details, including which 30 probes and why, are in
187-
[`docs/ci.md`](docs/ci.md).
187+
`docs/ci.md`.
188188

189189
### "Expectation corrected"
190190

‎docs/Doxyfile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,10 @@ INPUT = groups.dox \
145145
pages/exit-leg-activation.md \
146146
pages/quantity-intent.md \
147147
native-settlement.md \
148+
../CONTRIBUTING.md \
149+
../CODE_OF_CONDUCT.md \
150+
../LEGAL.md \
151+
../SECURITY.md \
148152
design \
149153
adr
150154

‎docs/adr/0001-kernel-adapter-boundary.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -300,10 +300,10 @@ citations, 264 are in `src/source/` and its headers; 6 sit in kernel files
300300
COVERAGE block carries one line per public member of `NativeStrategyHost` with either its C
301301
spelling or the reason it has none, and `scripts/check_native_c_api_surface.py` proves the
302302
block is exactly that class's public surface. `strategy_create` / `run_backtest` stay
303-
codegen-emitted (`include/pineforge/pineforge.h:434`), which is why a C host frees its report
303+
codegen-emitted (`include/pineforge/pineforge.h:530`), which is why a C host frees its report
304304
with `strategy_native_report_free_v1`.
305-
- **The examples are a gated target with executed assertions.** Thirteen Pine-free hosts ship
306-
under `examples/native/` — eleven C++ and two C — each including only
305+
- **The examples are a gated target with executed assertions.** Fifteen Pine-free hosts ship
306+
under `examples/native/` — thirteen C++ and two C — each including only
307307
`<pineforge/native_host.hpp>` (or `native_c_api.h`), linking `PineForge::kernel`, and checking
308308
its own numbers before it prints its summary line. `PINEFORGE_BUILD_EXAMPLES`
309309
(`CMakeLists.txt:37`, default OFF) builds them (`add_subdirectory` `CMakeLists.txt:305`) and
@@ -419,8 +419,8 @@ on a Release and on a Debug archive: `0 findings`, both profiles, with these ali
419419
|---|---|---|---|---|
420420
| `pf_equity_stats_t::sharpe_tv` | `sharpe_monthly` | public C ABI (`include/pineforge/pineforge.h`, `PF_ABI_VERSION` 4) | the next `PF_ABI_VERSION` (5) | The field is month-end-resampled equity simple returns (chart timezone, open-time bucketing), risk-free 2 %/yr, annualized ×√12, sample (N−1) stddev — a construction whose name is its resampling period, not its calibration source. The published header is the contract of every compiled FFI consumer, so both names are one `double` behind a C11 anonymous union of two same-typed members: identical offset (48), identical `sizeof(pf_equity_stats_t)` (120), identical `offsetof(pf_metrics_t, equity)` (648), pinned by `static_assert` in `src/c_abi.cpp` and exercised from C by `tests/test_c_abi.c`. |
421421
| `pf_equity_stats_t::sortino_tv` | `sortino_monthly` | public C ABI (as above) | the next `PF_ABI_VERSION` (5) | Same resampling as `sharpe_monthly`, population downside deviation vs the monthly risk-free. Aliased on the same terms; offset 56. |
422-
| `exit_legs::Domain::Coof` | `FillRecalc` | standalone C++ ABI `pineforge::exit_legs::lifecycle_v1` (`include/pineforge/exit_leg_lifecycle.hpp`) | `lifecycle_v2` | The domain is the fill-recalculation re-entry pass: the host re-runs its script after a fill and observes the rest of the same bar. `coof` abbreviates `calc_on_order_fills`, the Pine adapter's name for it (the same abbreviation the `coof_*` reflection rows carry, ruled above). An enumerator alias adds a name and no value: `Coof == FillRecalc == 1`, the underlying type stays `uint8_t`, `Domain::RawTicks` stays 4 (so `valid_frame`'s range check is unchanged), and no `switch` gains a case. Twin-parity-frozen TUs keep compiling their old spelling unchanged. |
423-
| `exit_legs::Domain::MagnifierCoof` | `MagnifierFillRecalc` | standalone C++ ABI `lifecycle_v1` (as above) | `lifecycle_v2` | The same re-entry pass on a magnified sub-bar. `MagnifierCoof == MagnifierFillRecalc == 3`. |
422+
| `exit_legs::Domain::Coof` | `FillRecalc` | standalone C++ ABI `pineforge::exit_legs::lifecycle_v1` (`include/pineforge/exit_leg_lifecycle.hpp`) | `lifecycle_v2` | The domain is the fill-recalculation re-entry pass: the host re-runs its script after a fill and observes the rest of the same bar. `coof` abbreviates `calc_on_order_fills`, the Pine adapter's name for it (the same abbreviation the `coof_*` reflection rows carry, ruled above). An enumerator alias adds a name and no value: `Coof == FillRecalc == 1`, the underlying type stays `uint8_t`, `Domain::RawTicks` stays 4 (so `valid_frame`'s range check is unchanged), and no `switch` gains a case. Twin-parity-frozen TUs keep compiling their old spelling unchanged. | <!-- verified HEAD -->
423+
| `exit_legs::Domain::MagnifierCoof` | `MagnifierFillRecalc` | standalone C++ ABI `lifecycle_v1` (as above) | `lifecycle_v2` | The same re-entry pass on a magnified sub-bar. `MagnifierCoof == MagnifierFillRecalc == 3`. | <!-- verified HEAD -->
424424

425425
**The serialized report keys do not change.** `sharpe_tv` and `sortino_tv` remain the JSON keys of
426426
the report dictionaries built by `docker/run_json.py` (`_stats_dict`, driven off the ctypes
@@ -614,7 +614,7 @@ buildable archive with no source-layer object in it; size with `Sized` or with y
614614
let the kernel record the equity curve, the per-bar broker hashes and the open-position row, or
615615
record them yourself; declare higher-timeframe series and an auxiliary finer feed in the run
616616
spec; declare a margin model, a risk block and a price grid; and submit, replace, cancel, bracket
617-
and trail through one request type. Thirteen example hosts do exactly that, each asserting its own
617+
and trail through one request type. Fifteen example hosts do exactly that, each asserting its own
618618
numbers in a gated CTest row, and the `kernel` profile of `scripts/ci_verify.py` runs the whole
619619
suite with no adapter compiled.
620620

‎docs/ci.md‎

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -304,9 +304,9 @@ drifted".
304304

305305
## Documentation guards
306306

307-
Three guards hold the published documentation to the tree. All three run from
308-
the source alone — no build, no corpus — and the first two are `ci_preflight`
309-
stages.
307+
Four guards hold the published documentation to the tree. Three of them run
308+
from the source alone — no build, no corpus — and are `ci_preflight` stages;
309+
the fourth is the documentation build.
310310

311311
`scripts/check_doc_anchors.py` checks every `file:line` citation the pages
312312
make: the file must resolve, the line must exist, and when a backticked symbol
@@ -343,26 +343,35 @@ python3 scripts/check_doc_lint.py
343343
```
344344

345345
Both guards are wired into `scripts/ci_preflight.py` as `doc-anchors` and
346-
`doc-lint`, and both run **advisory**: the stage runs, prints its offenders and
347-
is recorded as `reported`, but its failure does not fail the preflight. That is
348-
deliberate and temporary. They fail on HEAD by design — the citations and the
349-
sentences they name are exactly what the two page-rewriting lanes L14-B and
350-
L14-C exist to correct — and a red stage on the integration branch before those
351-
lanes land would block every other lane's verification. `--strict-docs` makes
352-
them binding today, and L14-B/C leave it on:
346+
`doc-lint`, and both are **binding**: a bad anchor or a stale sentence fails
347+
the preflight, like any other stage. They ran advisory for one integration
348+
window — the citations and the sentences they named were exactly what the two
349+
page-rewriting lanes were written to correct, and a red stage on the
350+
integration branch would have blocked every other lane's verification — and the
351+
`--strict-docs` flag that promoted them was removed with that state: the pages
352+
are clean, and a guard that can be asked not to bind is decoration. The
353+
advisory *mechanism* remains in `ci_preflight.py` for the next guard that lands
354+
before the drift it names is gone; no stage uses it today.
353355

354356
```sh
355-
python3 scripts/ci_preflight.py --strict-docs
357+
python3 scripts/ci_preflight.py # doc-anchors and doc-lint among its stages
356358
```
357359

358-
Their own self-tests, `doc-anchors-tests` and `doc-lint-tests`, are never
360+
Their own self-tests, `doc-anchors-tests` and `doc-lint-tests`, were never
359361
advisory, and both register as CTest rows (`test_doc_anchors`, `test_doc_lint`).
360-
A guard that cannot fail is decoration.
361362

362-
The third guard is the documentation build. `docs/build.sh` runs Doxygen over
363+
The third source-only guard is `scripts/check_design_inventory.py`
364+
(`design-inventory`, with its own `design-inventory-tests` suite). It was
365+
fail-closed from the day it landed: it reads `docs/design/native-feature-parity.md`
366+
§1, replays `tests/CMakeLists.txt`'s own decision about which units the kernel
367+
profile compiles, and fails when an inventory row's closure marker does not
368+
match what the tests actually drive. `--ctest-list` cross-checks its transliteration
369+
against real `ctest -N` output in both directions.
370+
371+
The fourth guard is the documentation build. `docs/build.sh` runs Doxygen over
363372
the whole public surface — every header under `include/pineforge`, the C API
364-
and C ABI headers, the ten native examples, the adapter units, the pages, the
365-
design document and the ADR — and then reads `docs/site/doxygen-warnings.log`.
373+
and C ABI headers, the fifteen native examples, the adapter units, the pages,
374+
the front-door documents, the design document and the ADR — and then reads `docs/site/doxygen-warnings.log`.
366375
Doxygen's `WARN_AS_ERROR` is global, which would let a stale comment in a
367376
legacy adapter header stop the site from building, so the gate is scoped in the
368377
script instead: a warning in the guarded set — `native_host.hpp`,

0 commit comments

Comments
 (0)