Repository navigation
Docs/agent onboarding - #249
Closed
Ghostfusion wants to merge 6 commits into
Closed
Ghostfusion wants to merge 6 commits into
Ghostfusion wants to merge 6 commits into
Conversation
added 6 commits
October 18, 2026 00:48
Onboarding entry point for AI agents (and new contributors) picking up this repository cold: layer map, the enforced ground rules, the change-routing table, execution paths, commands, verification ladder, and the known doc-vs-code traps that must not be trusted. Derived from a read-only familiarization pass of 4822bb9; no source files were modified. Every referenced path was verified to exist, and `bash scripts/check-consistency.sh` still reports 19 pass / 0 fail / 12 warn (the pre-existing warnings), i.e. this document adds none. Facts stated here come from the repository's own code, docs and artifacts, so no external search was needed; the doc-vs-code table labels the claims that remain unverified as such rather than asserting them. The working agreements supplied by the owner are reproduced verbatim in section 1.
With `core.autocrlf=true` (the Windows default from the GitHub guidance) this clone checks `scripts/*.sh` out as CRLF, so `bash scripts/*.sh` dies with `$'\r': command not found` — and a Windows working copy is also the Docker build context, so the same files would reach Linux containers unnormalized. Nothing pinned the ending: there was no `.gitattributes` anywhere. Adds `.gitattributes` with `*.sh text eol=lf`. Search established this as the per-repository fix that overrides the contributor's local setting: GitHub's "Configuring Git to handle line endings" states a committed .gitattributes "overrides the core.autocrlf setting for all repository contributors", and gitattributes(5) documents `eol` as setting "a specific line-ending style to be used in the working directory" without content checks (git-scm.com/docs/gitattributes); `text eol=lf` is the documented form for files that must keep LF "even on Windows". Second source: GitHub's own example attributes file, which recommends explicit attributes for this reason. Verified after committing: `rm scripts/check-consistency.sh && git checkout --` it, then the file has 0 CRLF / 297 LF and `bash scripts/check-consistency.sh` runs to completion (it previously aborted on `$'\r'`). Blob content was already LF (index `i/lf`), so no renormalization commit is needed.
`cache_manager.py` had no importer (only self-references) and could not even be imported: `get_cache_manager()` does `from inalpha_shared.db import get_db_pool`, and `inalpha_shared.db` exports no such symbol, so any use would raise ImportError. Its docstring said the wiring "will be called from backfill.py in a later PR"; that never happened, and backfill implements its own admission control. Deleting it is the fix: an unimportable module with no caller is worse than no module. Verified: `grep -rn` over the repository finds no remaining reference.
Read-only audit findings; comments only, no behavior change: - `execution/gateway.py` promised a `LiveGateway` "from D-6" and linked a `docs/refs/vnpy.md` that does not exist in this repository. No live gateway exists; simulated fills come from `SimulatedExchange` + the DB-side executor. - `execution/__init__.py` described risk rules as landing in the orchestration layer; they live in `risk_rules/`, enforced by `RiskEngine` in the kernel and `RiskGuard` on the HTTP path (which persists `risk_locks`). - `engine/__init__.py` promised a `LiveEngine`; the live path reuses the same kernel through `engine/live_session.py`, driven by `TestClock` from closed bars. - `api/health.py` claimed paper does not touch the DB "until D-7"; paper is fully DB-backed and `/health` is deliberately liveness-only. - `strategy_authoring/fitness.py` documented the turnover penalty as `turnover / 252`; the code computes `(trades / bars_processed) * 100`. - `kernel/clock.py` framed `LiveClock.set_timer` as a pending D-5 gap; it is unimplemented and the live path does not use timers at all. No test asserted any of these strings.
Read-only audit findings; documentation and comments only, no behavior change: - `docs/01-architecture-overview.md` (the page labelled "current architecture") claimed subagents `orchestrator → trader / risk` (removed in D-8a′; one agent exists) and `memory/ PostgresStore` (`LibSQLStore` under `.data/`), and undercounted lifecycle hook events as "5 + Stop" (six are defined). Box-drawing widths preserved so the diagram stays aligned. - `packages/orchestration/README.md` repeated the subagent claim. - `packages/orchestration/src/mastra/memory.ts` carried pre-production instructions (call `assertScopedRequest` from an `apps/web` route; "switch to PostgresStore before prod") that no longer describe this repository: the web app is static, the dashboard BFF is the entry, and identity middleware binds the authenticated subject. The invariant is kept: `resourceId` must come from the authenticated session, never from the client. - `apps/dashboard/src/i18n/routing.ts` pointed at `src/middleware.ts`; the file is `src/proxy.ts`. - `AGENTS.md` pointed readers at a `docs/brand/` directory that does not exist. - `services/evolver/.../evaluator/runner.py` said the evaluator "needs the data service" while passing an empty bar list; it now states that bars are empty and that the production path is `FrozenDatasetEvaluator`. `bash scripts/check-consistency.sh`: 0 failures; the `AGENTS.md` false-reference warning is gone and no remaining warning names a file touched here.
The guide listed the audit findings as live traps; the ones fixed here move to a
"corrected in this branch" table, and the still-open items keep the reason they
were left alone (owner decision, unverifiable, maintainer-owned, or needing a
coordinated change).
Also drops a claim of the guide's own that did not survive verification: it
asserted that `CLAUDE.md` and the PR template make mypy a CI red line. Neither
file says that; `CONTRIBUTING.md §9` ("ruff must pass, mypy best-effort") matches
`.github/workflows/ci.yml` (`uv run mypy . || true`).
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.
What this PR does / 这个 PR 做了什么
Briefly describe the change (1–3 sentences). For bug fixes, link the related issue:
Fixes #...简述变更内容（1–3 句）。如果是 bug fix，链接对应 issue：
Fixes #...Scope / 涉及范围
services/data/services/paper/services/research/packages/orchestration/ otherfeat/fix/refactor/docs/test/choreSelf-review checklist / 自检清单
<type>(<scope>): <desc>in English (seeCLAUDE.md §3), with one logical change per commit.bash scripts/check-consistency.shlocally; all checks pass.services/_shared/,.mastra/, ordocs/miro/(shared infrastructure & private decision records — seeCLAUDE.md §3for the rationale).Testing / 测试
Describe how you verified the change is correct — manual repro steps, new tests added, or smoke-test output.
简述你怎么验证这个改动是对的。可以是手动复现步骤、新加的测试用例、或 smoke test 输出。
Screenshots / recordings (if applicable) / 截图 / 录屏（如适用）
For UI or agent-behavior changes, please attach before/after comparisons.
UI 或 agent 行为变化请贴对比。