Repository navigation
docs(auth): describe pesu-auth 5.x in the agent docs, skills and roles - #7
Merged
Merged
Conversation
pesu-dev/auth now has its own docs/ directory, with architecture.md, metrics.md and testing.md among its pages. The AGENTS.md, skills and roles here used `docs/<name>.md` as shorthand for `.agents/pesudev-skills/auth/docs/<name>.md`, so in that repository the same path named two different files, and an agent following `docs/testing.md` could read either one. Every reference to a reference doc now uses its full path, and AGENTS.md says that any other path, `docs/<name>.md` included, is relative to the repository root. The README's pointer to the Dependabot steps names `auth/docs/ci-cd.md` for the same reason. No content changes.
pesu-auth 5.0.0 (pesu-dev/auth#241) moved from driving PESU Academy's web login to the API its mobile app uses, and later releases changed CI, testing and the docs around it. The agent material still described the old service: a CSRF prefetch cache and lock, HTML selectors, a single PESU session, a 95% coverage gate, missing values left out of the response, separate lint/docker/source workflows, and files that no longer exist. Agents following it would "fix" code back towards 4.x. Reference docs: - upstream.md: the login and profile requests, how each profile field is read and the rules the maintainers set for values (as PESU sends them, one source, null when missing; only a structural change is a 422; parse errors never logged). - api-contract.md: every route including the API Explorer, HEAD routes and security headers; the request limits; null rather than absent; all 17 fields; 404/405/body-parse errors in the standard body; the contract and docs tests; exactly-one-step versioning with patch defined. - architecture.md, metrics.md, testing.md: point at the repository's own docs/ pages, which tests/unit/test_docs.py keeps current, and keep only what agents need on top: invariants, patch points, fixture recipes (upstream, wire, payload fixtures), the maintainers' test style. - ci-cd.md: the CI Checks jobs, Dependabot, and the production release (approval, rollback, release, then main). - security.md, conventions.md: the access token, upstream models that drop unread data, log injection, message vs detail, container and --locked installs; ruff now linting tests. - known-issues.md: drops the entries fixed since (CSRF logging, requirements.txt, the bug template, test_readme.py, pytest.raises assertions, the PR template title, the README username) and records what is misleading today. AGENTS.md: rule 1 says the whole profile is logged by design; rule 8 drops the one-session claim (PESU allows several sessions) but keeps live runs single and never looped; rule 9 is the one-step bump; a new rule says values are returned as PESU sends them, or null. Skills and roles follow the same facts; change-upstream-client, update-scraper, benchmark, fix-ci, run-locally, run-tests, setup-environment, update-dependencies, write-tests and diagnose-production are rewritten. update-scraper and scraper-specialist keep their names so links to them still work. Four role descriptions change (ci-investigator, docs-writer, scraper-specialist, test-engineer), so pesu-dev/auth's sync-agents check needs the wrappers regenerated with the submodule bump. Also covers pesu-dev#6 (--locked installs, the benchmark dependency group, ruff from uv.lock, the CI job table) and replaces the em dashes in the report templates.
A second pass over every file against pesu-dev/auth dev: - api-contract.md: the standard error body is for 4xx and 5xx (a 308 has none), and a ResponseModel failure is the route's own PESUAcademyError(500), not the catch-all handler. - architecture.md: the runtime image holds the virtualenv as well as app/. - testing.md: test_docs.py checks that the tables list everything and that named paths exist, not that paths are "reflected"; dropped an unsourced line about test docstrings. - conventions.md: the examples of why-comments are long, so say new ones should be shorter rather than contradict them. - update-scraper: the capture script writes the raw response, so say plainly that it holds real data to redact and delete, instead of a comment claiming it was already redacted. - Rewrapped the prose lines the earlier edits had pushed well past 100 columns.
8 of 30 tasks
TVA-2
pushed a commit
to TVA-2/auth
that referenced
this pull request
Oct 24, 2026
* chore: update the agent skills to pesu-dev/skills 588c9bb pesu-dev/skills#7 rewrote auth's agent docs, skills and roles for 5.x. They still described 4.x: a CSRF prefetch cache, HTML scraping, a single PESU session, a 95% coverage gate and missing values left out of the response, so agents following them would have worked against the current code. The reference docs are now named by their full .agents/pesudev-skills/auth/docs/ path, so they no longer clash with this repository's own docs/, and they point at those pages where they overlapped. Four roles' descriptions changed (ci-investigator, docs-writer, scraper-specialist, test-engineer), so their Copilot custom agents in .github/agents/ are regenerated with scripts/sync_agents.py; the sync-agents hook fails without it, which is why Dependabot's own bump cannot land as is. * chore: bump version to 5.7.0
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.
The
auth/material still described pesu-auth 4.x. Since then, 5.0.0 (pesu-dev/auth#241) moved to the API PESU Academy's mobile app uses, and later releases reworked CI, testing and the docs. Agents reading it were told about:lint,dockerandsourceworkflowsAn agent following that would "fix" the code back towards 4.x. This PR brings everything in line with pesu-dev/auth
dev(5.6.0).1. Reference docs named by full path (
fb6de9e)pesu-dev/auth now has its own
docs/(architecture.md,metrics.md,testing.md, ...). Here,docs/testing.mdwas shorthand for.agents/pesudev-skills/auth/docs/testing.md, so in that repo one path named two files.Every reference to a reference doc now uses its full path.
AGENTS.mdsays any other path,docs/<name>.mdincluded, is relative to the repository root. No content changes.2. 5.x content (
1faeaca)upstream.mdnullwhen missing; only a structural change is a 422; parse errors are never loggedapi-contract.md/docs, HEAD routes, security headers); request limits;nullrather than absent; 404, 405 and unreadable-body errors in the standard body; the Schemathesis contract tests andtest_docs.py; one-step versioning with patch defined; v5.0.0 as a breaking-change precedentarchitecture.md,metrics.md,testing.mddocs/pages, whichtests/unit/test_docs.pykeeps current. They keep only what agents need on top: invariants, patch points, fixture recipes (upstream,wire, payload fixtures) and the maintainers' test style. Open HTTP clients at rest is now0, not1ci-cd.mdmainsecurity.md,conventions.mdmessagevsdetail, the non-root container,--lockedinstalls, and ruff linting testsknown-issues.mdAGENTS.mdnullchange-upstream-client,update-scraper,benchmark,fix-ci,run-locally,run-tests,setup-environment,update-dependencies,write-testsanddiagnose-productionare rewritten; the rest are updated. The em dashes in the report templates are replacedupdate-scraperandscraper-specialistkeep their names so links to them keep working;known-issues.mdsays why.common/is unchanged: it still mentionssource.yaml, which other pesu-dev repos may use, and auth'sAGENTS.mdtakes precedence where the two disagree.Closes #6
How this was checked
devand the running app: HEAD on every page, the 404 and 405 bodies and theAllowheader, security headers, and the 400 for a badfmt.uvx pre-commit run --all-filespasses.After merge
Four role descriptions change:
ci-investigator,docs-writer,scraper-specialistandtest-engineer. Dependabot's submodule bump in pesu-dev/auth will therefore failsync-agents. It needs a PR from a fork that bumps.agents/pesudev-skills, runsuv run python scripts/sync_agents.pyand bumps the version (auth/docs/ci-cd.md, "Dependabot submodule bumps").🤖 Generated with Claude Code