From 6572151a131ef676f83a4983c7ee698dbc36442b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 28 May 2026 11:20:49 +0000 Subject: [PATCH] =?UTF-8?q?chore(docs):=20end-of-day=202026-05-28=20.md=20?= =?UTF-8?q?sweep=20=E2=80=94=20fix=208=20MUST-FIX=20+=206=20SHOULD-FIX=20c?= =?UTF-8?q?ross-doc=20drifts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comprehensive .md housekeeping closing today's 11-PR session day. Output of docs-reviewer (sonnet) full Tier 1 + Tier 2 audit on main (post-PR-#299) — verdict NEEDS-CROSS-REF-FIX with 14 prioritized findings; this PR applies all 8 MUST-FIX + 6 SHOULD-FIX. 3 NICE-TO-FIX deferred to follow-up. Scope (7 files, doc-only): - SKILL.md schema-version history table (line 240) — prepend 2 new rows: 0.10.9-phase4.6 (PR #297, 4 *_wall_clock_seconds fields + 195m timeout + cache canary, empirically validated cron Run #71) + 0.10.10-phase4.6 (PR #300 in flight — Issue #67 follow-up per- sector delta). Closes the canonical-history gap where PR #297 + PR #300 were absent. - PHASE_STATUS.md §Current state — schema row 0.10.8 → 0.10.9 + PR #300 in-flight note; Post-tag production patches row extended with PR #295/#296/#297/#298/#299 SHAs + one-liners; Production run pointer 0ad1d574 cron #69 → 368dccd9 cron Run #71 with the PR #297 wall-clock empirical numbers + Issue #288 cache-replay smoking gun (multi_class_per_class_attempt_count=0 + fundamentals_latency_p50_seconds=0.0). Recently merged block extended 6 → 11 PRs. Issue closure status updated. Next deliverables refreshed: Issue #67 flip removed (PR #294 already executed); item 2 now = Issue #287 PR B FORM4 revert; PR #300 per-sector delta added as item 3. Open issues list refreshed (#288 + #289 marked closed; #287 PR A vs PR B split). - CLAUDE.md §Phase status Recently merged block — extended 6 → 11 PRs with full SHA + one-liner per PR. New "In flight" sub-section added for PR #300. - AGENTS.md §Phase + version state — Production-verified run cron #69 (233117ac, 13m 16s) → cron Run #71 (368dccd9, 14m 32s, 2026-05-28 08:44 UTC, schema 0.10.7 → 0.10.9-phase4.6); 4 new wall-clock field values cited; Issue #288 cache-replay smoking gun captured; closed-issue note for #288 + #289 + #287 PR A. - CONTEXT.md §Live snapshot — schema 0.10.8 → 0.10.9 + PR #300 in-flight note; new "Post-tag patches" row listing PRs #292-#299 + PR #300 in flight; cron status cron #69 2026-05-27 → Run #71 2026-05-28; Sector-CoE row updated with empirical 132 → 109; §Roadmap Stage 0 description refreshed. - WORKFLOW.md §Agentic 6-Phase Cadence session-start protocol — inline schema 0.10.7-phase4.6 replaced with current 0.10.9-phase4.6 + pointer guidance to PHASE_STATUS.md §Current state as the canonical bump-per-schema-PR target. Closes the recurring inline- schema drift pattern. - PHASE_STATUS_INFLIGHT.md — this PR's in-flight entry appended per PR #237 side-file convention. docs-reviewer lockstep cross-check after this PR: - SCHEMA_VERSION: ALIGNED across all 6 canonical docs at 0.10.9-phase4.6 with PR #300 in-flight note where applicable - Defense layer 33 declared: ALIGNED (was already) - USE_SECTOR_COE = True post-PR #294: ALIGNED (was stale in AGENTS.md issue #67 framing + PHASE_STATUS.md Next deliverables; both fixed) - Subagent count 18: ALIGNED (was already) - Skill count 45: ALIGNED (was already) - Latest cron Run #71 368dccd9: ALIGNED (was stale in AGENTS.md + PHASE_STATUS.md + CONTEXT.md; all fixed) - Issue #288 + #289 closure status: ALIGNED (was stale as open in AGENTS.md + PHASE_STATUS.md; both fixed) 3 NICE-TO-FIX deferred: - README.md Honest Limitations does not reference Phase 4.6 honest re-validation harness (PR #283). Coverage gap, not break. - WORKFLOW.md Phase 4.5 row cites v1.2.0; technically closed at v1.3.0-phase4.5e. Historical-context only. - METHODOLOGY.md USE_SECTOR_COE framing needs verification before edit. Hard constraints honored: - No code / scoring / schema / valuation / Rule 16 / Top-5 invariant touched - No new defense flag · No new dep · No new env-var - Markdown-only diff (no JSON / YAML / Python / TS change) - Schema version UNCHANGED on main at 0.10.9-phase4.6 (PR #300 will bump 0.10.10 on its merge) - AGENTS.md substance lockstep with CLAUDE.md per the established delegation pattern Verification: - ruff check . PASS (no Python touched) - python -m compute.output.schema_check PASS (no schema touched) - pytest tests/ -m "not network" N/A (no test surface) - Cross-reference grep — all 7 anchor strings consistent across all 6 docs after fix https://claude.ai/code/session_01AGU8d6pm4u2fQQ5cebg9qa --- AGENTS.md | 30 ++++++++++++++------- CLAUDE.md | 14 +++++++--- CONTEXT.md | 13 ++++----- PHASE_STATUS.md | 31 +++++++++++++-------- PHASE_STATUS_INFLIGHT.md | 58 ++++++++++++++++++++++++++++++++++++++++ SKILL.md | 4 ++- WORKFLOW.md | 14 +++++----- 7 files changed, 127 insertions(+), 37 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d5067ed7b..d5853f1b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -374,16 +374,26 @@ list lives in [`CLAUDE.md`](CLAUDE.md) §Phase status. Schema-version history table is in [`SKILL.md`](SKILL.md). This file's role is to note cross-tool-specific points only: -- Production-verified run: cron #69 (`233117ac`, 13m 16s warm-cache, - 2026-05-28) — useful for non-Claude agents validating local compute - output against a known-good baseline. Verified by `defense-layer- - auditor` Section A-J + `stock-detail-auditor` deterministic prefilter - on schema `0.10.7-phase4.6`; 7 active vetoes firing as expected (NVDA - rank 1 correctly suppressed by `beneish_manipulation_veto`); Rule 16 - Top-5 rotation invariant holds with PPG carrying the `entered_top5` - badge. Known follow-ups: issue #288 (GOOG/GOOGL display market_cap - 2.2× inflated; composite unaffected), issue #289 (NVR DQIC ceiling - false positive; `/stock/NVR` renders empty fair-price section). +- Production-verified run: cron **Run #71** (`368dccd9`, 14m 32s + warm-cache, 2026-05-28 08:44 UTC) — useful for non-Claude agents + validating local compute output against a known-good baseline. + Verified by `defense-layer-auditor` Section A-L + `stock-detail- + auditor` deterministic prefilter on schema `0.10.9-phase4.6`; 7 + active vetoes firing as expected (NVDA rank 1 correctly suppressed + by `beneish_manipulation_veto` + `sloan_accruals_top_decile`); + Rule 16 Top-5 rotation invariant holds with PPG carrying the + `entered_top5` badge. PR #297 4 new `Metadata.*_wall_clock_seconds` + fields populated correctly (`tier2=10.6s`, `form4=null` per + FORM4_FETCH_SKIP, `osap=347.1s`, `cross_source=133.2s`); PR #294 + sector-CoE flip empirically validated (`value_trap_risk` 132 → 109, + −23 tickers, −17.4%); PR #293 NVR fair_price section renders + correctly. **Closed same-day issues**: #288 (PR #292 + PR #298 + cache-v5 follow-up; smoking gun `multi_class_per_class_attempt_count=0` + + `fundamentals_latency_p50_seconds=0.0` confirmed cache-replay + bypass; fix will land on cron Run #72 with fresh fetch) · #289 + (PR #293 Site-2 retirement). Known follow-up: Issue #287 PR B + (FORM4 revert, gated on ≥ 1 cron < 195m green; PR #297 ceiling + bump active). - Open Phase 4+ issues: #15 (SEC throttling) · #41 (Next 14→16 CVE bump; 15 advisories open, all zero-exploitability on static-export deployment) · #67 (sector-CoE flip-PR; data-collection landed diff --git a/CLAUDE.md b/CLAUDE.md index 52c4d761d..49eb907b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -549,14 +549,22 @@ ladder closure + LedgerCraft frontend reskin (defense layer 32 → 33; PR #264 `multi_class_aggregate_shares_suspected` + PR #265 DQIC site-2 rename `valuation_output_anomalous`). -**Recently merged** (PR #286 → PR #294, 2026-05-28 — 6 PRs same day post-v1.4.0): -- PR #294 `0ddb6b81` — feat(valuation): Issue #67 — flip `USE_SECTOR_COE = True` (Damodaran 11-sector Ke) +**Recently merged** (PR #286 → PR #299, 2026-05-28 — **11 PRs same day post-v1.4.0**): +- PR #299 `3ec4b29e` — chore(docs): end-of-day housekeeping — drain 3 INFLIGHT (#295/#297/#298) + pointer bumps +- PR #298 `030675e9` — fix(ci): Issue #288 follow-up — bump workflow cache key `cache-v4 → cache-v5` (forces fresh fetch on Run #72 so PR #292 GOOG/GOOGL Branch 3 actually fires; closes silent-failure gap surfaced by PR #297 Rule 18 disambiguator) +- PR #297 `ecb60e64` — feat(perf): Issue #287 PR A — durable timeout + per-loop wall-clocks (schema `0.10.8 → 0.10.9-phase4.6`; `timeout-minutes: 150 → 195` + cache-restore canary + 4 `Metadata.*_wall_clock_seconds` fields; empirically validated cron Run #71) +- PR #296 `e85dfbcf` — docs(context): add root `CONTEXT.md` pointer + reconcile `docs/agents/domain.md` (single-file orientation bridge for upstream tools) +- PR #295 `2d2ec83e` — chore(docs): post-session housekeeping — drain 6 INFLIGHT + bump pointers +- PR #294 `0ddb6b81` — feat(valuation): Issue #67 — flip `USE_SECTOR_COE = True` (Damodaran 11-sector Ke; `value_trap_risk` 132 → 109 cohort drop) - PR #293 `95e638bf` — fix(valuation): Issue #289 — retire Site-2 DQIC ceiling (NVR FP, methodology Option C) - PR #292 `e9aaab31` — fix(ingest): Issue #288 — GOOG/GOOGL XBRL concept-name omission (schema `0.10.7 → 0.10.8-phase4.6`) - PR #291 `cb9114bb` — docs(agents): AGENTS.md substance refresh (cron #51 → #69 pointer; 11 open-issues list) - PR #290 `dea8e3ad` — chore(cleanup): post-cron-#69 — BK orphan removal + 3 doc drifts - PR #286 `27361047` — chore(docs): housekeeping PR-B — drain INFLIGHT + bump pointers post-v1.4.0 -- (3 issues filed: #287 / #288 / #289; 4 comments posted on #41 / #115 / #130 / #137) +- (3 issues filed + ALL closed same day: #287 PR A merged via #297 [PR B FORM4 revert remaining] · #288 closed via #292 + #298 · #289 closed via #293) + +**In flight** (not yet merged on `main`): +- PR #300 — feat(scoring): Issue #67 follow-up — per-sector `value_trap_risk` delta instrumentation (schema `0.10.9 → 0.10.10-phase4.6`; methodology-scientist Mode B Q2 deferred from PR #294) **Earlier** (PR #264 → PR #285, 2026-05-26 → 2026-05-27): - PR #285 `8f373758` — docs(release): codify mobile-only operator convention for tag releases diff --git a/CONTEXT.md b/CONTEXT.md index 2ebf6dcdf..248ee4831 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -42,15 +42,16 @@ See [`README.md`](README.md) for the user-facing pitch + | Field | Value | |---|---| -| Schema version | **`0.10.8-phase4.6`** (verify: `python -m compute.output.schema_check`) | +| Schema version | **`0.10.9-phase4.6`** on `main` (verify: `python -m compute.output.schema_check`). PR #300 in flight: `0.10.10-phase4.6` (Issue #67 follow-up per-sector delta) | | Active phase | **Phase 4.6** — Honest re-validation harness (Hou-Xue-Zhang 2020 + McLean-Pontiff 2016 32% decay banner) | | Defense layer | **33 declared boolean flags** (7 active vetoes + 26 annotates + reserved; ~27 currently emit) + 5 numerical guards + `manipulation_index` rollup | -| Latest release | [**`v1.4.0-phase4.6`**](https://github.com/dackclup/quantrank/releases/tag/v1.4.0-phase4.6) (2026-05-27, `bbca9cac`) | -| Universe provider | historical S&P 500 membership (PR #274) | -| Sector-CoE | `USE_SECTOR_COE = True` (PR #294 flip; Damodaran 2019 Ch. 8.4 11-sector Ke) | +| Latest release | [**`v1.4.0-phase4.6`**](https://github.com/dackclup/quantrank/releases/tag/v1.4.0-phase4.6) (2026-05-27, `bbca9cac`) — Phase 4.6 honest re-validation harness | +| Post-tag patches | PR #292 GOOG/GOOGL XBRL · #293 NVR DQIC retire · #294 sector-CoE flip · #295 housekeeping · #296 CONTEXT.md · #297 PR #287 PR A wall-clocks · #298 cache-v5 · #299 housekeeping (all merged 2026-05-28); PR #300 per-sector delta in flight | +| Universe provider | historical S&P 500 membership (PR #274 Hou-Xue-Zhang 2020) | +| Sector-CoE | `USE_SECTOR_COE = True` (PR #294 flip; Damodaran 2019 Ch. 8.4 11-sector Ke; cron Run #71 confirmed `value_trap_risk` 132 → 109) | | Sub-agent roster | 18 agents in 4 tiers (4 opus + 14 sonnet) | | Skill inventory | 45 (vendored + project-internal) | -| Cron status | weekday cron #69 green on 2026-05-27 | +| Cron status | weekday cron Run #71 green (2026-05-28 08:44 UTC, `368dccd9`, 14m 32s warm cache; empirically validated PR #297 wall-clock fields) | For chronological detail: [`PHASE_STATUS.md`](PHASE_STATUS.md) + append-only side-file [`PHASE_STATUS_INFLIGHT.md`](PHASE_STATUS_INFLIGHT.md). @@ -241,7 +242,7 @@ S&P 1500 universe expansion), see [`PHASE_STATUS.md`](PHASE_STATUS.md) §"Next deliverables" + [`WORKFLOW.md`](WORKFLOW.md) per-phase task lists. Headline phases: -- **Stage 0** (immediate): Cron #70 confirmation + Issue #287 closure +- **Stage 0** (immediate): Issue #287 PR B FORM4 revert (single-line, gated on ≥ 1 cron < 195m green with `form4_wall_clock_seconds` populated; PR #297 ceiling bump active so headroom confirmed by cron Run #71 14m 32s) · PR #300 per-sector delta merge confirmation - **Stage 1**: Phase 4.5e PR 5 cluster-weight promotion 5.0 -> 7.0 - **Stage 2**: Phase 4 factor integrations (4h.2 / 4j.1 / 4k.1) -> `v1.5.0-phase4` - **Stage 3**: Phase 5 ML meta-learner (LightGBM + Triple-Barrier + Conformal + SHAP) -> `v1.6.0-phase5` diff --git a/PHASE_STATUS.md b/PHASE_STATUS.md index da3f3d32d..da8634b94 100644 --- a/PHASE_STATUS.md +++ b/PHASE_STATUS.md @@ -17,25 +17,33 @@ | Field | Value | |---|---| -| Schema | **`0.10.8-phase4.6`** (PR #292 PATCH bump 2026-05-28 — Rule 18 disambiguator `Metadata.multi_class_per_class_attempt_count` for the GOOG/GOOGL XBRL concept-name omission fix; supersedes `0.10.7-phase4.6` PR #283 release) | +| Schema | **`0.10.9-phase4.6`** (PR #297 PATCH bump 2026-05-28 — 4 new `Metadata.*_wall_clock_seconds` fields for Tier-2 / Form-4 / OSAP / Step-8 cross_source loops; paired with `compute-rankings.yml` `timeout-minutes: 150 → 195` + cache-restore canary; empirically validated on cron Run #71 / `368dccd9`. Supersedes `0.10.8-phase4.6` PR #292.) **In flight on PR #300**: `0.10.10-phase4.6` — Issue #67 follow-up `Metadata.value_trap_risk_delta_by_sector` per methodology-scientist Q2 verdict | | Defense layer | **33 declared boolean flags** (7 active vetoes + 26 annotates + reserved slots; ~27 currently emit; `USE_SECTOR_COE = True` post-PR #294 flip) · plus 5 numerical guards + `manipulation_index` rollup | | Active vetoes | **7** — `altman_distress` · `sloan_accruals_top_decile` · `net_issuance_top_decile` · `non_reliance_filing` · `beneish_manipulation_veto` · `dechow_manipulation_veto` · `data_quality_input_corruption` | | Latest release tag | [**`v1.4.0-phase4.6`**](https://github.com/dackclup/quantrank/releases/tag/v1.4.0-phase4.6) — 2026-05-27 at `bbca9cac` (Phase 4.6 honest re-validation harness) | -| Post-tag production patches | PR #292 (`e9aaab31`, schema `0.10.7 → 0.10.8-phase4.6`, GOOG/GOOGL XBRL fix) · PR #293 (`95e638bf`, Site-2 DQIC retirement, NVR FP) · PR #294 (`0ddb6b81`, sector-CoE flip `USE_SECTOR_COE = True`, Issue #67 closure) | +| Post-tag production patches | PR #292 (`e9aaab31`, schema `0.10.7 → 0.10.8-phase4.6`, GOOG/GOOGL XBRL fix) · PR #293 (`95e638bf`, Site-2 DQIC retirement, NVR FP) · PR #294 (`0ddb6b81`, sector-CoE flip `USE_SECTOR_COE = True`, Issue #67 closure) · PR #295 (`2d2ec83e`, post-session housekeeping drain 6 INFLIGHT + pointer bumps) · PR #296 (`e85dfbcf`, add root CONTEXT.md pointer + reconcile `docs/agents/domain.md`) · PR #297 (`ecb60e64`, schema `0.10.8 → 0.10.9-phase4.6`, Issue #287 PR A durable timeout + 4 `*_wall_clock_seconds` fields) · PR #298 (`030675e9`, cache-key `v4 → v5` to flush stale parquet so PR #292 GOOG/GOOGL fix actually fires; closes Issue #288 silent-failure gap) · PR #299 (`3ec4b29e`, end-of-day INFLIGHT drain of #295/#297/#298) | | Prior release tag | [**`v1.3.0-phase4.5e`**](https://github.com/dackclup/quantrank/releases/tag/v1.3.0-phase4.5e) — 2026-05-26 at `5db3b978` (Phase 4.5e Form-4 cluster + LedgerCraft reskin; defense layer headline 32 → 33) | -| Production run | `0ad1d574` (2026-05-28 cron #69, post-PR #290 main HEAD; sector-CoE flip + #292 + #293 land in cron #70 Mon-Fri 22:00 UTC) | +| Production run | `368dccd9` (2026-05-28 cron Run #71, 14m 32s warm cache, post-PR #298 cache-v5 bump; empirically validated PR #297 wall-clock fields — `tier2_wc=10.6s`, `form4_wc=null` per FORM4_FETCH_SKIP, `osap_wc=347.1s`, `cross_source_wc=133.2s`. Smoking gun for Issue #288 cache-replay bypass: `multi_class_per_class_attempt_count=0` + `fundamentals_latency_p50_seconds=0.0`) | | Universe | 502 stocks (S&P 500 minus 1 delisting) | | Skill inventory | **45** invocation-triggerable + phase planning docs | | Subagent inventory | **18** project-specific in 4 tiers: **Tier 1 Core** (`quantrank-reviewer` · `schema-sentinel` · `defense-layer-auditor` · `edgar-debugger` · `stock-detail-auditor`) · **Tier 2 Lifecycle** (`security-reviewer` · `frontend-design-reviewer` · `vercel-preview-auditor` · `release-captain` · `phase-coordinator`) · **Tier 3 Specialized** (`test-engineer` · `methodology-scientist` · `literature-searcher` · `performance-engineer` · `dependency-auditor`) · **Tier 4 Operations** (`docs-reviewer` · `ci-triage-engineer` · `incident-commander`) | -**Recently merged** (PR #286 → PR #294, 2026-05-28; 6 PRs landed same day post-v1.4.0 release): +**Recently merged** (PR #286 → PR #299, 2026-05-28; **11 PRs landed same day post-v1.4.0 release**): +- PR #299 `3ec4b29e` — chore(docs): end-of-day housekeeping — drain 3 INFLIGHT markers + bump pointers (drains PR #295/#297/#298) +- PR #298 `030675e9` — fix(ci): Issue #288 follow-up — bump workflow cache key `cache-v4 → cache-v5` (closes the GOOG/GOOGL silent-failure gap; PR #292 Branch 3 fix code was correct but warm-cache replay short-circuited it; surfaced by PR #297 Rule 18 disambiguator) +- PR #297 `ecb60e64` — feat(perf): Issue #287 PR A — durable timeout + per-loop wall-clocks (schema `0.10.8 → 0.10.9-phase4.6`; `compute-rankings.yml` `timeout-minutes: 150 → 195` + cache-restore canary step; 4 new `Metadata.*_wall_clock_seconds` fields with 4 distinct defensive patterns; pre-push 3-reviewer gate green) +- PR #296 `e85dfbcf` — docs(context): add root `CONTEXT.md` pointer + reconcile `docs/agents/domain.md` (single-file orientation bridge for upstream tools expecting CONTEXT.md; multi-file analog remains canonical) +- PR #295 `2d2ec83e` — chore(docs): post-session-housekeeping — drain 6 INFLIGHT markers + bump pointers - PR #294 `0ddb6b81` — feat(valuation): Issue #67 — flip `USE_SECTOR_COE = True` (Damodaran 2019 Ch. 8.4 11-sector Ke; methodology-scientist Mode B APPROVED; `value_trap_risk` 132 → 109 cohort drop, within target [80, 110] band) - PR #293 `95e638bf` — fix(valuation): Issue #289 — retire Site-2 DQIC ceiling (NVR FP; methodology-scientist Option C; Site-1 + Defense #4 `extreme_*_estimate` + Issue #177 Huber-breakdown layer cover the remaining corruption + breakdown cases) - PR #292 `e9aaab31` — fix(ingest): Issue #288 — GOOG/GOOGL XBRL concept-name omission (`market_cap` 2.2× inflated since PR #269; schema `0.10.7 → 0.10.8-phase4.6` for Rule 18 disambiguator) - PR #291 `cb9114bb` — docs(agents): AGENTS.md substance refresh (production-verified run pointer cron #51 → cron #69; open-issues list 4 → 11 entries) - PR #290 `dea8e3ad` — chore(cleanup): post-cron-#69 — BK orphan removal + 3 doc drifts (security-reviewer W1+W2 + edgartools 2.30 → 5.31) - PR #286 `27361047` — chore(docs): housekeeping PR-B — drain INFLIGHT + bump pointers post-v1.4.0 -- (3 issues filed: #287 FORM4 revert + durable 5-loop timeout · #288 GOOG/GOOGL XBRL · #289 NVR DQIC; 4 comments posted on #41/#115/#130/#137) +- (3 issues filed: #287 FORM4 revert + durable 5-loop timeout · #288 GOOG/GOOGL XBRL · #289 NVR DQIC; all closed same day via PR #297 / #298 / #292 / #293) + +**In flight** (not yet merged on `main`): +- PR #300 — feat(scoring): Issue #67 follow-up — per-sector `value_trap_risk` delta instrumentation (schema `0.10.9 → 0.10.10-phase4.6`; new `Metadata.value_trap_risk_delta_by_sector: dict[str, int] | None`; methodology-scientist Mode B Q2 deferred from PR #294; sets up Q3 2026-08-19 cohort audit shape evidence) **Earlier** (PR #264 → PR #285, 2026-05-26 → 2026-05-27): - PR #285 `8f373758` — docs(release): codify mobile-only operator convention for tag releases (CLAUDE.md §Gotchas + release-tag SKILL.md + release-captain agent) @@ -103,13 +111,14 @@ **Next deliverables** (parallelizable, pick by appetite): -1. **Phase 4.5e PR 5 — cluster weight promotion 5.0 → 7.0** — after ≥ 1 cron's `form4_rule10b5_one_excluded_count` lands and the `-30%` to `-45%` firing-rate delta confirms the Aboody et al. 2010 §3.2 midpoint; vesting-residual risk still argues against full 10.0 restoration -2. **Issue #67 sector-CoE flip PR** — `config.USE_SECTOR_COE = True` after ≥ 1 cron confirms `value_trap_risk` delta-count (target: ~176 → ~80-110); data-collection merged via PR #204 -3. **v1.5.0 release tag (next)** — gated on Phase 4.5e PR 5 cluster weight promotion (item 1) + Issue #67 sector-CoE flip (item 2) landing post-cron; or cut a `v1.4.x` patch sooner if a structural fix lands on its own -4. **Phase 4i.1 / 4j.1 / 4k.1 — Factor integrations** (JKP / Qlib / IPCA; ~1-2w each → `v1.1.0-phase4`); 4i.1 license-review-required per #115 -5. **Phase 5 — ML meta-learner** (~10-12w); also unblocks PR 4b §3 IC-decay writer (#75) +1. **Phase 4.5e PR 5 — cluster weight promotion 5.0 → 7.0** — after Issue #287 PR B (FORM4 revert) merges + ≥ 1 cron's `form4_rule10b5_one_excluded_count` lands and the `-30%` to `-45%` firing-rate delta confirms the Aboody et al. 2010 §3.2 midpoint; vesting-residual risk still argues against full 10.0 restoration +2. **Issue #287 PR B — FORM4 revert** — single-line revert of `FORM4_FETCH_SKIP=1` from `.github/workflows/compute-rankings.yml` env block, gated on ≥ 1 cron < 195m green with `form4_wall_clock_seconds` populated (PR #297's 195m timeout + canary now active; cron Run #71 confirmed 14m 32s warm cache leaves ample headroom). Unblocks PR 5 cluster weight gate-data accumulation for Q3 cohort audit +3. **Issue #67 follow-up PR #300** (in flight) — per-sector `value_trap_risk` delta instrumentation; methodology-scientist Q2 deferred from PR #294; populates per-sector breakdown of the 132 → 109 aggregate drop on cron Run #72+ for Damodaran shape verification +4. **v1.5.0 release tag (next)** — gated on Phase 4.5e PR 5 cluster weight promotion (item 1) + Issue #287 PR B (item 2) landing + ≥ 4 weekly crons of post-flip / post-revert data accumulating ahead of Q3 2026-08-19 cohort audit; or cut a `v1.4.x` patch sooner if a structural fix lands on its own +5. **Phase 4i.1 / 4j.1 / 4k.1 — Factor integrations** (JKP / Qlib / IPCA; ~1-2w each → `v1.1.0-phase4`); 4i.1 license-review-required per #115 +6. **Phase 5 — ML meta-learner** (~10-12w); also unblocks PR 4b §3 IC-decay writer (#75) -**Open issues**: #15 (fundamentals throttling) · #16 (going-concern negation-lookbehind — FP rate 1.0% in band, mechanism not yet code-confirmed) · #41 (Next.js 14 → 16 CVEs, 15 open `next@14.x` advisories — zero exploitability on static-export) · #67 (sector-CoE flip, data-collection merged PR #204) · #75 (PR 4b §3 IC-decay, Phase-5-blocked) · #115 (JKP license review) · #130 (quarterly cohort-threshold review, next 2026-08-19) · #137 (9arm-skills license clarification, 4-week deadline from 2026-05-20) · #150 (Phase 2-3 epic, phases 2-3 remaining) +**Open issues** (as of post-PR-#299, with PR #300 in flight): #15 (fundamentals throttling) · #16 (going-concern negation-lookbehind — FP rate 1.0% in band, mechanism not yet code-confirmed) · #41 (Next.js 14 → 16 CVEs, 15 open `next@14.x` advisories — zero exploitability on static-export) · #67 (sector-CoE flipped via PR #294; per-sector delta follow-up in flight via PR #300) · #75 (PR 4b §3 IC-decay, Phase-5-blocked) · #115 (JKP license review, blocks Phase 4i.1) · #130 (quarterly cohort-threshold review, next 2026-08-19) · #137 (9arm-skills license clarification, deadline 2026-06-17) · #150 (Phase 2-3 epic, phases 2-3 remaining) · #287 (PR A merged via PR #297; PR B FORM4 revert gated on ≥ 1 cron < 195m green). **Closed same day 2026-05-28**: #288 (PR #292 + PR #298 cache-v5 follow-up) · #289 (PR #293 Site-2 DQIC retirement). --- diff --git a/PHASE_STATUS_INFLIGHT.md b/PHASE_STATUS_INFLIGHT.md index 711660677..7d41f61ca 100644 --- a/PHASE_STATUS_INFLIGHT.md +++ b/PHASE_STATUS_INFLIGHT.md @@ -2682,3 +2682,61 @@ Bodies preserved (historical record). CLAUDE.md §Phase status pointer updated t PHASE_STATUS_INFLIGHT.md side-file satisfies §Conventions "ship with every PR" lockstep per PR #237 convention. The drain pattern itself is the same template used in PR #286 (post-v1.4.0 cycle) — keeping the side-file disciplined as the project pattern. --- + +## PR (this PR) — End-of-day 2026-05-28 comprehensive .md sweep: fix 8 MUST-FIX + 6 SHOULD-FIX drifts across 6 canonical docs (in flight, 2026-05-28) + +Comprehensive `.md` housekeeping closing the 11-PR session day. Output of `docs-reviewer` (sonnet) full Tier 1 + Tier 2 audit on `main` (post-PR-#299) — verdict **NEEDS-CROSS-REF-FIX** with 14 prioritized findings. + +**Scope (6 canonical docs)**: + +- **`SKILL.md`** — schema-version history table at line 240 prepended with 2 new rows: `0.10.9-phase4.6` (PR #297 — 4 `*_wall_clock_seconds` fields + 195m timeout + cache canary, empirically validated cron Run #71) + `0.10.10-phase4.6` (PR #300 in flight — Issue #67 follow-up per-sector delta). Closes the gap where PR #297 + PR #300 schema bumps were absent from the canonical history. + +- **`PHASE_STATUS.md`** §Current state — schema row `0.10.8 → 0.10.9` + PR #300 in-flight note; Post-tag production patches row expanded with PR #295/#296/#297/#298/#299; Production run pointer `0ad1d574` cron #69 → `368dccd9` cron Run #71 with the PR #297 wall-clock empirical numbers + Issue #288 cache-replay smoking-gun. Recently merged block extended 6 PRs → 11 PRs. Issue closure status: #287 (PR A merged, PR B gated) · #288 (closed via #292 + #298) · #289 (closed via #293). Next deliverables refreshed: Issue #67 flip removed (PR #294 already executed); item 2 now = Issue #287 PR B FORM4 revert; PR #300 per-sector delta added as item 3. + +- **`CLAUDE.md`** §Phase status — Recently merged block extended 6 → 11 PRs with full SHA + one-liner per PR. New "In flight" sub-section added for PR #300. + +- **`AGENTS.md`** §Phase + version state — Production-verified run cron #69 (`233117ac`, 13m 16s) → cron Run #71 (`368dccd9`, 14m 32s, 2026-05-28 08:44 UTC, schema `0.10.7 → 0.10.9-phase4.6`); 4 new wall-clock field values cited (`tier2=10.6s`, `form4=null`, `osap=347.1s`, `cross_source=133.2s`); Issue #288 cache-replay smoking gun captured; closed-issue note for #288 + #289 + #287 PR A. + +- **`CONTEXT.md`** §Live snapshot — schema `0.10.8 → 0.10.9` + PR #300 in-flight note; new "Post-tag patches" row listing PRs #292-#299 + PR #300 in flight; cron status cron #69 2026-05-27 → Run #71 2026-05-28; Sector-CoE row updated with empirical 132 → 109 figure; §Roadmap Stage 0 description refreshed: "Cron #70 confirmation + Issue #287 closure" → "Issue #287 PR B FORM4 revert (single-line, gated on cron < 195m + form4 wall-clock populated) · PR #300 merge confirmation". + +- **`WORKFLOW.md`** §Agentic 6-Phase Cadence session-start protocol — inline schema `0.10.7-phase4.6` replaced with current `0.10.9-phase4.6` + pointer guidance to PHASE_STATUS.md §Current state as the canonical bump-per-schema-PR target (closes the recurring inline-schema drift pattern). + +**3 NICE-TO-FIX items deferred** (per docs-reviewer recommendation): + +1. README.md Honest Limitations section does not yet reference the Phase 4.6 honest re-validation harness (PR #283 Hou-Xue-Zhang 2020 survivorship-bias fix + McLean-Pontiff 2016 32% decay banner). Coverage gap, not a cross-reference break. Defer to a follow-up README polish PR. +2. WORKFLOW.md Phase 4.5 row at line 83 cites `v1.2.0` tag; Phase 4.5e ladder technically closed at `v1.3.0-phase4.5e`. Historical-context only — no session confusion risk. +3. METHODOLOGY.md `USE_SECTOR_COE` framing may still say "future flip" pending; needs Read confirmation before edit. Defer to follow-up methodology pass. + +**docs-reviewer Lockstep summary cross-check after this PR**: + +- `SCHEMA_VERSION`: ALIGNED across CLAUDE.md / PHASE_STATUS.md / SKILL.md / CONTEXT.md / WORKFLOW.md / AGENTS.md at `0.10.9-phase4.6` (main) with PR #300 in-flight note where applicable +- Defense layer `33 declared`: ALIGNED (was already) +- `USE_SECTOR_COE = True` post-PR #294: ALIGNED (was stale in AGENTS.md issue #67 framing + PHASE_STATUS.md Next deliverables — both fixed) +- Subagent count 18: ALIGNED (was already) +- Skill count 45: ALIGNED (was already) +- Latest cron Run #71 `368dccd9`: ALIGNED (was stale in AGENTS.md + PHASE_STATUS.md + CONTEXT.md — all fixed) +- Issue #288 + #289 closure status: ALIGNED (was stale as open in AGENTS.md + PHASE_STATUS.md — both fixed) + +**Scope (7 files, doc-only)**: + +- `SKILL.md` · `PHASE_STATUS.md` · `CLAUDE.md` · `AGENTS.md` · `CONTEXT.md` · `WORKFLOW.md` — substance updates per punch list +- `PHASE_STATUS_INFLIGHT.md` — this entry appended per PR #237 side-file convention + +**Hard constraints honored**: + +- No code / scoring / schema / valuation / Rule 16 / Top-5 invariant touched +- No new defense flag · No new dep · No new env-var +- Markdown-only diff (no JSON / YAML / Python / TS change) +- Schema version UNCHANGED on `main` at `0.10.9-phase4.6` (PR #300 will bump 0.10.10 on its merge) +- AGENTS.md substance lockstep with CLAUDE.md per the established delegation pattern + +**Verification ladder**: + +- `ruff check .` — N/A (no Python touched) +- `python -m compute.output.schema_check` — N/A (no schema touched; passes trivially) +- `pytest tests/ -m "not network"` — N/A (no test surface) +- `grep` cross-reference check — all 7 anchor strings (schema version / cron pointer / `USE_SECTOR_COE` / 18 / 45 / 33 / `v1.4.0-phase4.6`) consistent across all 6 docs after fix + +PHASE_STATUS_INFLIGHT.md side-file satisfies §Conventions "ship with every PR" lockstep per PR #237 convention. Doc-only PR; closes the comprehensive cross-doc drift surface tracked by `docs-reviewer` 2026-05-28 audit. + +--- diff --git a/SKILL.md b/SKILL.md index 161ea48c4..4ad8633e6 100644 --- a/SKILL.md +++ b/SKILL.md @@ -237,7 +237,9 @@ Schema versions: | `0.7.0-phase4g` | Phase 4g | **8-K Tier-2 event defenses re-enabled** (PR #79, merged 2026-05-15 on `c35c6d40`, closes [issue #14](https://github.com/dackclup/quantrank/issues/14)). Flipped `compute/scoring/tier2._EIGHT_K_DEFENSES_ENABLED = True` after the PR 3d workflow-timeout deferral (root cause cleared by PR #58 cache layers + PR 3d tenacity tightening). `non_reliance_filing` (Item 4.02 hard veto, 365d lookback, Schroeder 2024 SSRN — ~50% of 4.02 filings precede formal restatement) returns to the active layer as the **5th active veto**. `auditor_change` (Item 4.01 annotate, 730d lookback, Reg S-K Item 304, Cohen-Malloy-Nguyen 2020 type) joins the Tier-2 annotate surface. No data-schema-shape delta — only the feature-flag flip + reason-taxonomy expansion. | | `0.7.1-phase4g` | Phase 4g | **`price_change_1d_pct` additive field** (squash-merged via PR #80, commit `1509f707`). New optional `float \| None` field on `StockSummary` + `StockDetail` — day-over-day percent change from the prior trading-day close. Computed once in `compute/main.py:_fetch_prices_one` from the last two valid yfinance closes; null for newly-IPO'd tickers (only one close available). Lets the ranking-table mobile cards render a change pill without lazy-fetching 502 per-stock history JSONs. Per `phase-4/schema-versioning/PLAN.md`: "Add a new optional field (default = None) → patch". Production metadata.version stays `0.7.0-phase4g` until next weekly compute. | | `0.7.1-phase4g` (no schema delta) | Phase 4.5a-4.5d wave | **Earnings-manipulation defense cluster — sub-PRs 4.5a + 4.5b + 4.5c + 4.5d shipped 2026-05-16/17** (PRs #89/#90/#91 + #93 + #95 + #97). **No data-schema-shape delta** — all 9 new flag identifiers are strings appended to existing `risk_flags: list[str]` (active vetoes) + `valuation_warnings: list[str]` (annotates) arrays. Active vetoes **5 → 7**: + `beneish_manipulation_veto` (Beneish 1999, M > −1.78) + `dechow_manipulation_veto` (Dechow 2011, F > 3.0). Annotates added: `manipulation_triple_flag` (4.5a joint gate, 2 fired: SMCI · WAT), `restatement_history` (4.5b, 59 fired / 11.8% — Hennes-Leone-Miller 2008 *TAR*), `late_filing_notification` (4.5b, 2 fired: HAS · Q — Bartov-Lai-Yeung 2002 *JAR*), `rem_suspect` (4.5c, 16 fired / 3.2% — Roychowdhury 2006 *JAE* 3-proxy REM via per-sector OLS), `accruals_momentum_high` (4.5d, 50 fired / 10.0% — Sloan 1996 / Beneish 1999 Δ(TATA) > +0.05 over 3y), `loss_avoidance_pattern` (4.5d, 0 fired — Burgstahler-Dichev 1997 cohort thresholds too tight for S&P 500 large-cap universe, file as follow-up). Also closes [issue #7](https://github.com/dackclup/quantrank/issues/7) (Sloan over-firing on Financials: 21.3% → 11.7%, sector spread 7.7× → 1.4×). 2 new cache dirs (`compute/cache/edgar_amendments/` + `compute/cache/edgar_late_filings/`, 7d TTL each). Test suite **646 → 831 offline**. Reason taxonomy: 24 stable + 2 Tier-3 + 2 new vetoes + 6 new annotates = **34 stable identifiers**. | -| **`0.10.8-phase4.6`** (PR #292 merged 2026-05-28 `e9aaab31`) | Issue #288 — GOOG/GOOGL XBRL concept-name omission fix | **PATCH bump** for new Rule 18 disambiguator `Metadata.multi_class_per_class_attempt_count`. PR #269 (`5bf38c12`) per-class XBRL override never fired in production since landing — `_fetch_shares_from_per_filing_xbrl` queried only 2 of the 3 needed XBRL concepts (`us-gaap:CommonStockSharesOutstanding` was the missing one; Alphabet files per-class share counts under this concept). Fix adds the missing concept to the tuple; counter disambiguates "branch never reached" (attempt=0) vs "XBRL returned None" (attempt>0, override=0). GOOG/GOOGL display `market_cap` corrected from ~$4.66T/$4.71T to ~$2.09T/~$2.59T per class; composite/rankings UNAFFECTED. Annotate-only safety net (`multi_class_aggregate_shares_suspected`) continues to fire. 4 new regression tests authored by `test-engineer`. | +| **`0.10.10-phase4.6`** (PR #300 — in flight 2026-05-28) | Issue #67 follow-up — per-sector `value_trap_risk` delta instrumentation | **PATCH bump** for new `Metadata.value_trap_risk_delta_by_sector: dict[str, int] \| None` field per methodology-scientist Mode B Q2 verdict (deferred from PR #294). Keyed by GICS sector name; values are `without_sector_coe[sector] - with_sector_coe[sector]` — positive = sector dropped flags after `USE_SECTOR_COE = True` flip (Damodaran 2019 Ch. 8.4 predicts Utilities / Real Estate / Consumer Staples positive; Information Technology / Energy negative). Computed every cron regardless of `USE_SECTOR_COE` so Q3 2026-08-19 cohort audit has visible per-sector shape. Tests 1367 → 1369 (+2 schema-contract). ZERO scoring change; field nullable per Rule 18. | +| **`0.10.9-phase4.6`** (PR #297 merged 2026-05-28 `ecb60e64`) | Issue #287 PR A — durable timeout + per-loop wall-clocks | **PATCH bump** for 4 new `Metadata.*_wall_clock_seconds: float \| None` fields (`tier2`, `form4`, `osap`, `cross_source`). Paired with `.github/workflows/compute-rankings.yml` `timeout-minutes: 150 → 195` + cache-restore canary step (10 cache dirs, ~30s) that surfaces cache eviction before any SEC fetch begins. 4 distinct defensive patterns: Tier-2 outer try/except wraps ThreadPoolExecutor (None on interpreter failure); Form-4 start INSIDE the `else:` branch (None when `FORM4_FETCH_SKIP=1` per Issue #287 PR B gate); OSAP start before try (None in except; QR_SKIP_OSAP still populates a small float because it bypasses freshness gate only); Step 8 always populated. Wall-clock fields semantically distinct from `fundamentals_latency_p95_seconds` — those measure per-ticker p95 (tenacity-cascade detector); these measure total loop duration (budget-overrun + cache-eviction detector). Empirically validated on cron Run #71 (`368dccd9`, 2026-05-28 08:44 UTC): all 4 fields populated correctly, total ~8.2 min instrumented under 195m ceiling. Companion PR #298 cache-v5 bump closes the silent-failure gap surfaced by this PR's Rule 18 instrumentation (PR #292 Branch 3 fix never fired due to warm-cache replay short-circuit). | +| **`0.10.8-phase4.6`** (PR #292 merged 2026-05-28 `e9aaab31`) | Issue #288 — GOOG/GOOGL XBRL concept-name omission fix | **PATCH bump** for new Rule 18 disambiguator `Metadata.multi_class_per_class_attempt_count`. PR #269 (`5bf38c12`) per-class XBRL override never fired in production since landing — `_fetch_shares_from_per_filing_xbrl` queried only 2 of the 3 needed XBRL concepts (`us-gaap:CommonStockSharesOutstanding` was the missing one; Alphabet files per-class share counts under this concept). Fix adds the missing concept to the tuple; counter disambiguates "branch never reached" (attempt=0) vs "XBRL returned None" (attempt>0, override=0). GOOG/GOOGL display `market_cap` corrected from ~$4.66T/$4.71T to ~$2.09T/~$2.59T per class on cron Run #72+ (cache-v5 bump per PR #298 forces fresh fetch); composite/rankings UNAFFECTED. Annotate-only safety net (`multi_class_aggregate_shares_suspected`) continues to fire. 4 new regression tests authored by `test-engineer`. | | **`0.10.7-phase4.6` @ tag `v1.4.0-phase4.6`** (PR #283 release 2026-05-27 `bbca9cac`) | Phase 4.6 honest re-validation harness | **MINOR bump** for Phase 4.6 additive `Metadata` fields landing across PRs #274-#282 (universe-provenance + survivorship-bias historical S&P 500 membership per Hou-Xue-Zhang 2020 RFS + ranking history time-series loader via git-archive + forward-return loader from gitignored price cache + per-pillar Spearman IC orchestrator via rank-then-Pearson, no scipy dep + manipulation-index distribution shift report). `scripts/generate_honest_baseline.py` CLI added with McLean-Pontiff 2016 32%-decay banner pinned in 5-phrase mandatory disclaimer. ZERO scoring / Top-5 / composite delta — all additive observability + offline-validation modules. | | **`0.10.6-phase4.5e`** (PR #269 merged 2026-05-26 `5bf38c12`) | Issue #261 PR-B — per-class XBRL extraction | **Structural fix for GOOG/GOOGL `$4.6T` overcount.** New `config.MULTI_CLASS_OVERCOUNT_ALLOWLIST: dict[str,str]` mapping ticker → exact XBRL class-member string (`GOOGL → "us-gaap:CommonClassAMember"`, `GOOG → "goog:CapitalClassCMember"` ← **filer-specific namespace gotcha** per edgar-debugger probe). `_fetch_shares_from_per_filing_xbrl` extended with `target_class_member` parameter; new elif branch in `_build_snapshot` fires when ticker is on allowlist + primary is plausible aggregate-shape. 2 new `Metadata` fields: `multi_class_per_class_override_count` (expected ~2 = GOOG + GOOGL) + `multi_class_mc_reconcile_failure_count` (Rule-18 defensive). PATCH — additive. ZERO behavior change for 500 non-allowlist tickers. | | **`0.10.5-phase4.5e`** (PR #264 merged 2026-05-26 `d9c62292`) | Issue #261 PR-A — multi-class CIK-collision annotate | **New `multi_class_aggregate_shares_suspected` annotate** + Rule 18 `Metadata.multi_class_aggregate_shares_suspected_count: int \| None`. Fires when two or more tickers share the same CIK AND each ticker's market_cap > 10% of universe-median (`MARKET_CAP_FLOOR_RATIO = 0.10`). Annotate-only; composite rank unchanged. Defense layer 32 → 33 declared. Expected steady-state firing ≈ 6 (GOOG / GOOGL / NWS / NWSA / FOX / FOXA). PATCH — additive `Metadata` field only. Companion PR #265 renamed Site-2 DQIC emission to `valuation_output_anomalous` without schema delta. | diff --git a/WORKFLOW.md b/WORKFLOW.md index 14fbb1f6d..c08f4227a 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -41,12 +41,14 @@ Monitoring) onto the 18 subagents already in `.claude/agents/` and the established commands. No new infrastructure. **Session-start protocol**: read [`PHASE_STATUS.md`](PHASE_STATUS.md) -§"Current state" first — currently schema `0.10.7-phase4.6` (PR #283 -release closes Phase 4.6 honest re-validation harness; bumped through -PRs #269 GOOG/GOOGL per-class XBRL `0.10.5 → 0.10.6` + Phase 4.6 -Metadata additions `0.10.6 → 0.10.7-phase4.6`), defense layer -**33 declared** = 7 vetoes + 26 annotates, -release tag [`v1.4.0-phase4.6`](https://github.com/dackclup/quantrank/releases/tag/v1.4.0-phase4.6), +§"Current state" first as the canonical pointer (it bumps on every +schema PR; this prose stays stable). As of 2026-05-28 post-PR-#299: +schema `0.10.9-phase4.6` on `main` (PR #297 PATCH bump — 4 +`Metadata.*_wall_clock_seconds` fields + `compute-rankings.yml` +`timeout-minutes: 150 → 195` + cache-restore canary), with PR #300 +in flight bumping to `0.10.10-phase4.6` (Issue #67 follow-up per- +sector delta). Defense layer **33 declared** = 7 vetoes + 26 annotates; +release tag [`v1.4.0-phase4.6`](https://github.com/dackclup/quantrank/releases/tag/v1.4.0-phase4.6); CVE baseline **15 open** (0C / 6H / 7M / 2L) after PR #194 patch + PR #226 triage. Then route via the cadence below.