Skip to content

docs: bring specs back in line with the code - #173

Merged
mohammadp1001 merged 1 commit into
mainfrom
docs/sync-specs-with-code
Aug 9, 2026
Merged

docs: bring specs back in line with the code#173
mohammadp1001 merged 1 commit into
mainfrom
docs/sync-specs-with-code

Conversation

@mohammadp1001

Copy link
Copy Markdown
Owner

Section B of the round-3 audit: documentation-only drift. No behaviour changes, no code touched.

data-model.md

  • Config model still had ticker1/ticker2; it is tickers: list[str] with any number supported. extended_hours was missing entirely. session_money_budget now documents the > 0 rule (fix: session_money_budget has no positive-value check (config-schema.md) #170).
  • candle_timeframe was missing 10min and 15min.
  • Session id was documented as session-{random_seq}; it is a zero-padded ordinal, run-1/session-0001 - which is also what spec.md Clarification Q4 says, so the two specs contradicted each other.
  • execution_result values were EXECUTED/SKIPPED_BUDGET/SKIPPED_MARKET_CLOSED/SKIPPED_API_ERROR; the code writes EXECUTED/HOLD/FAILED, with the specific reason in ORDER_FAILED telemetry.
  • trailing_stop_high_watermark was documented as NULL for non-Momentum; it is seeded to entry_price for every position (trailing_stop_high_watermark is never initialised to entry_price #130).
  • "zero, one, or two Positions per Session" predated multi-ticker support.

contracts/agents.md, research.md

  • The execution-telemetry known gap was closed by feat: emit execution telemetry on every order path (#132) #141; both files still described it as open. Replaced with what is actually emitted, including remaining_session_budget.
  • research.md said the execution agent subclasses google.adk.BaseAgent and overrides _run_async_impl. It is a plain Python class with model = None; recorded why the ADK subclass was dropped.
  • The "EVALUATION_FAILED missing from EVENT_TYPES" note was also stale.

contracts/report-context.md

  • Named _run_session; the method is _process_session.
  • Omitted ticker_details[].execution_result, which is populated - the note that "execution_result is always None" was only true of the top-level field.
  • Said the feedback agent parses id="investment-thesis"; it is ticker-scoped as investment-thesis-{ticker} (Feedback agent extracts the wrong ticker's thesis from multi-ticker reports #134), with a documented fallback for older reports.

contracts/cli.md

spec.md

  • Said the investigation agent is invoked "per unblocked ticker"; it is invoked once with all unblocked tickers.

tasks.md

Left as a historical task record rather than rewritten, with a note at the top pointing at the two places it has been overtaken: the ordinal evaluation window (replaced by an absolute UTC deadline in #122) and the unscoped thesis id (#134).

609 passed in 139.57s (0:02:19)
Required test coverage of 100% reached. Total coverage: 100.00%
ruff check alphoryn/ tests/ -> All checks passed!

Section B of the round-3 audit: documentation-only drift, no behaviour changes.

data-model.md
- Config model still had ticker1/ticker2; it is tickers: list[str] with any
  number supported. extended_hours was missing. session_money_budget now
  documents the >0 rule.
- candle_timeframe was missing 10min and 15min.
- Session id was "session-{random_seq}"; it is a zero-padded ordinal,
  run-1/session-0001, which is also what spec.md Clarification Q4 says.
- execution_result values were EXECUTED/SKIPPED_BUDGET/SKIPPED_MARKET_CLOSED/
  SKIPPED_API_ERROR; the code writes EXECUTED/HOLD/FAILED, with the specific
  reason in ORDER_FAILED telemetry.
- trailing_stop_high_watermark was documented as NULL for non-Momentum; it is
  seeded to entry_price for every position (#130).
- "zero, one, or two Positions per Session" predated multi-ticker.

contracts/agents.md, research.md
- The execution-telemetry known gap was closed by #141; both files still
  described it as open. Replaced with what is actually emitted.
- research.md said the execution agent subclasses google.adk.BaseAgent and
  overrides _run_async_impl. It is a plain Python class with model = None;
  recorded why the ADK subclass was dropped.
- The EVALUATION_FAILED-missing-from-EVENT_TYPES note was also stale.

contracts/report-context.md
- Named _run_session; the method is _process_session.
- Omitted ticker_details[].execution_result, which is populated.
- Said the feedback agent parses id="investment-thesis"; it is ticker-scoped
  as investment-thesis-{ticker} (#134), with a fallback for old reports.

contracts/cli.md
- Documented 3 of 6 commands; version, verify-telemetry and reset were missing.
- --timeframe listed 3 of 5 values.
- --budget said "0 or negative = no limit"; negative is now rejected.
- Sample output used the old random-suffix session ids.

spec.md
- Said the investigation agent is invoked "per unblocked ticker"; it is invoked
  once with all unblocked tickers so it can reason about them side by side.

tasks.md
- Left as a historical task record, with a note at the top pointing at the two
  places it has been overtaken: the ordinal evaluation window (replaced by an
  absolute UTC deadline in #122) and the unscoped thesis id (#134).
@mohammadp1001
mohammadp1001 merged commit 4b50a3c into main Aug 9, 2026
3 checks passed
@mohammadp1001
mohammadp1001 deleted the docs/sync-specs-with-code branch August 9, 2026 13:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant