Skip to content

docs: fix agent doc links and capture extension test gotchas - #2266

Open
BenWeekes wants to merge 1 commit into
mainfrom
docs/extension-test-gotchas
Open

docs: fix agent doc links and capture extension test gotchas#2266
BenWeekes wants to merge 1 commit into
mainfrom
docs/extension-test-gotchas

Conversation

@BenWeekes

Copy link
Copy Markdown
Contributor

What

  • Fix AGENTS.md entry-point links: L2 deep dives live at docs/ai/L1/L2/ on main (the file pointed at a nonexistent docs/ai/L1/deep_dives/, so agents following the entry point missed all eight deep dives); also note that progressive-disclosure-standard.md lives on the docs/progressive-disclosure branch, not main.
  • Extension development deep dive: add ASR guarder contract gotchas learned from recent ASR extension work — positive/non-overlapping final timestamps (synthesize from the audio timeline when the vendor has no timing), invalid credentials must be non-fatal with reconnect-manager escalation (only HTTP 401/403 immediately fatal), connection_status tests are allowlist-gated, and capture guarder output to a log file to keep the pytest summary/exit code. Add the newer same-session finalize-reconnect and connection-status tests to the guarder table.
  • Setup: fresh-worktree bootstrap ordering (task install first; install_python_deps.sh alone fails before ten_packages/system exists).
  • Workflows: in-container lint always exits non-zero with E0401 import errors; judge against a known CI-green extension baseline.

Why

Process docs only — no code changes. These are the exact points that cost debugging time in recent extension work; capturing them makes the next extension land right the first time.

AGENTS.md pointed L2 deep dives at docs/ai/L1/deep_dives/, but on main
they live at docs/ai/L1/L2/, so agents following the entry point missed
all eight deep dives; it also linked a progressive-disclosure-standard
file that is not checked into main. Fix the path and note where the
standard actually lives.

Capture process lessons from recent asr extension work:

- asr guarder contract notes in the extension development deep dive:
  finals need positive, non-overlapping timestamps (synthesize from the
  audio timeline when the vendor returns no timing); invalid credentials
  must surface as non-fatal errors with reconnect-manager escalation
  (only http 401/403 are immediately fatal); connection_status tests are
  allowlist-gated; capture guarder output to a log file to keep the
  pytest summary and exit code. Add the newer same-session finalize
  reconnect and connection status tests to the guarder table.
- setup: on a fresh worktree run task install first — running
  install_python_deps.sh alone fails before ten_packages/system exists.
- workflows: in-container lint always exits non-zero with E0401 import
  errors; compare against a known ci-green extension baseline.
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