Skip to content

docs: align CLAUDE.md and make format with the code and CI - #256

Merged
glebedel merged 4 commits into
mainfrom
s2d2/audit-dev-docs
Nov 11, 2026
Merged

glebedel merged 4 commits into
mainfrom
s2d2/audit-dev-docs

Conversation

@glebedel

@glebedel glebedel commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What

CLAUDE.md (also AGENTS.md) had drifted from the code, and make format checked less than CI does.

Where Was Now Evidence
Key Patterns sample hit["account_id"] hit["available_accounts"][0]["id"] No hit has account_id (toolset.py search returns the server's actions plus session_id); README and MIGRATION use available_accounts. The sample raised KeyError.
top_k "per connector" "caps the whole result" toolset.py return [... for action in hits[:top_k]]; README and MIGRATION say the same
submit_feedback() account "the first account" "the lowest account id in scope" toolset.py account_ids=[min(scope)]; README and the docstring say lowest id
Dev dependency command uv add --dev pytest uv add --optional dev pytest Dev tools live in [project.optional-dependencies].dev; --dev would create a separate [dependency-groups] table
make format ty check stackone_ai ty check stackone_ai examples CI runs uv run ty check examples as its own step

How verified

  • uv run ty check stackone_ai examples: All checks passed.
  • Cross-checked each corrected statement against the source lines above.

Gates (head 32e0fed)

Gate Result
Repo skills none in repo
/forge:forge ran on df47b7f: no change (each claim checked against toolset.py); re-run on 32e0fed: 0 comment lines, 0 copies
Security scan security-reviewer agent: no finding at confidence 70 or above. Aikido: 31 open issues on main (lockfile CVEs, workflow SAST, one old test-fixture secret), none on lines this PR changes
Codex security clean on 32e0fed (job b2f55e81)
/security-review ran: secrets, input validation, transport and DoS items clean; the server-side items do not apply to an SDK
/code-review medium on df47b7f, 6 doc findings, all fixed: Key Patterns runs the hit's own action_id on its own account, the stale per-connector meta tool names are now stackone_search_actions / stackone_execute_action, the Commands and Testing lines say where examples are type-checked, and the format help says it needs make install extras=1
CI green on 32e0fed: 10 pass, 3 skipped
Unresolved review threads 0

Requested by guillaume@stackone.com in Slack (repo audit thread).

🤖 Generated with Claude Code


Summary by cubic

Aligns CLAUDE.md and make format with the actual code and CI behavior.

  • Names the global meta tools stackone_search_actions / stackone_execute_action, one pair across every account in scope, not per-connector.
  • Fixes the Key Patterns sample, which raised KeyError: hits carry available_accounts and action_id, and the example now runs the hit's own action on its own account, scoping submit_feedback() to that same account.
  • Corrects top_k to cap the whole merged result, matching toolset.py's hits[:top_k] slice.
  • Corrects submit_feedback() to use the lowest account id in scope (min(scope)), not the first account.
  • Updates the dev dependency command to uv add --optional dev pytest, since dev tools live in the dev extra.
  • Adds examples to make format type checks, matching CI so a clean local run won't fail CI.

Documentation and Makefile only; no runtime behavior changes.

Written for commit e702e5b. Summary will update on new commits.

View guided diff Turn on auto-fix

- The Key Patterns sample read hit["account_id"], which no search hit has;
  hits carry available_accounts, as README and MIGRATION show. It raised KeyError.
- top_k caps the merged result (toolset.search slices hits[:top_k]), not per connector.
- submit_feedback() goes through min(scope), the lowest account id, not the first.
- Dev tools live in the dev extra, so the add command is uv add --optional dev.
- CI type checks examples too; make format now does the same, so a clean
  local run cannot still fail CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
@glebedel glebedel self-assigned this Nov 10, 2026
s2d2-s1 and others added 2 commits November 11, 2026 00:54
CLAUDE.md still described per-connector _search_actions / _execute_action
tools, while the toolset uses one stackone_search_actions /
stackone_execute_action pair across every account in scope. The Key Patterns
example pinned the first hit's account but ran a hardcoded Linear action, so
the account and action could come from different connectors. make format now
type-checks examples, which needs the dev and examples extras.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
CLAUDE.md conflicted in the Key Patterns example: this branch corrects it
(search hits carry available_accounts and action_id) and main reformatted
it with ruff 0.17's markdown formatting. Kept the corrected example, now
formatted the way ruff expects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
Comment thread CLAUDE.md Resolved
submit_feedback() routes through the lowest account in scope, so the
example could send feedback through a different account than the one
that ran the action. Pass the same account_ids.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Guillaume Lebedel <10488548+glebedel@users.noreply.github.com>
@glebedel
glebedel merged commit 7fb0139 into main Nov 11, 2026
14 checks passed
@glebedel
glebedel deleted the s2d2/audit-dev-docs branch November 11, 2026 12:08
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.

2 participants