docs(review): PraisonAI PR #4774 (parity checker line-number masking) — no user-facing docs required, internal CI tooling only

[MervinPraison]

Source PR

• Repo: MervinPraison/PraisonAI
• PR: #4774 — fix(parity): a line number moving is not a parity failure
• Branch: fix/parity-report-line-churn → main
• Merged: 2026-09-03
• Head SHA: 749c30c6f771694f4460165ef084c8f58b5d8e0e
• Author: @MervinPraison
• Change size: +81 / -8, 6 files

Recommendation

No user-facing documentation update is required for this PR. This change is entirely internal CI/tooling plumbing for the parity checker used by PraisonAI maintainers. It does not touch any user-visible SDK API, agent feature, configuration option, or workflow.

If another agent picks this up, please do not create a page under docs/features/, docs/tools/, docs/guides/, or docs/concepts/ for this. Per AGENTS.md, documentation is user-focused and must not describe features absent from the user-visible surface of praisonaiagents/ — the parity checker lives in praisonai/_dev/parity/, which is a developer-only tree.

Only one small housekeeping follow-up may be relevant, and it is automatic (see "Mirrored file that auto-syncs" below).

What actually changed in PR #4774

The parity checker's --check mode was reddening main any time an unrelated edit shifted line numbers inside a covered file. Example: PR #4765 added ~20 lines above Agent.__init__, and the very next parity gate failed with:

FAILURES (2):
  - src/praisonai-ts/SIGNATURE_PARITY.md is out of date
  - src/praisonai-ts/signature-parity.json is out of date

The only difference in the report was:

-- Python: `praisonaiagents/agent/agent.py:583`
+- Python: `praisonaiagents/agent/agent.py:603`

Files touched

File	Kind	Change
src/praisonai/praisonai/_dev/parity/signatures/compare.py	Internal tool code	Adds strip_source_lines() — masks file.ext:123 → file.ext when comparing report content in --check; --write still records real line numbers.
src/praisonai/tests/unit/_dev/test_signature_parity.py	Tests	4 new tests: line shift is not staleness, content change still is, changed file path still is, prose numbers untouched.
.github/workflows/update-parity-tracker.yml	CI workflow	Installs the TypeScript compiler; regenerates the signature report (--write) on push to main; adds SIGNATURE_PARITY.md and signature-parity.json to the auto-commit file pattern.
src/praisonai-ts/SIGNATURE_PARITY.md	Auto-generated report	Regenerated — updated line numbers only (agent.py:583→603, execution_mixin.py:831→832).
src/praisonai-ts/signature-parity.json	Auto-generated report	Same regeneration — line numbers only.
src/praisonai/praisonai/_dev/parity/README.md	Internal dev README	+4 / −1 lines explaining line-number masking and that update-parity-tracker.yml regenerates both name and signature layers on push to main.

Behaviour delta

• --check still fails on: a changed parameter, a changed waiver, a surface moving to a different file, a waiver whose gap is closed, an expired waiver, a run comparing nothing.
• --check no longer fails on: a source line number shifting inside the same file.
• update-parity-tracker.yml now keeps the committed line numbers true after merges without any PR carrying the churn.

Why no user docs are needed

Verified against the user-doc conventions in AGENTS.md:

1. Not a user-facing feature. The parity checker is a maintainer tool for keeping the Python and TypeScript SDKs in sync at the signature level. End users of PraisonAI (developers, non-developers, beginners) never invoke it.
2. Not a new SDK export. No new class, function, config, parameter, or import path is introduced or renamed in praisonaiagents/.
3. Not agent-centric. The change has no impact on how users write agents, tasks, workflows, tools, memory, knowledge, MCP, or any other user-facing surface.
4. Auto-generated SDK reference is untouched. docs/sdk/reference/typescript/ and docs/sdk/reference/rust/ are generated by the docs parity system; this PR does not change SDK surfaces, so the auto-generator has nothing new to emit.
5. Not a concept, feature, tool, or guide. Placement under docs/concepts/ (human-only), docs/features/, docs/tools/, or docs/guides/ would violate folder rules and drop non-user content into user-facing navigation.

Mirrored file that auto-syncs (no action needed)

The PraisonAIDocs repo mirrors praisonai/_dev/ from the source repo via the daily update_repos.sh / .github/workflows/update-repos.yml workflow. After the next sync, praisonai/_dev/parity/README.md in this repo will pick up the +4/−1 wording from PR #4774 automatically. No manual edit is required, and this file is not part of the user documentation site (it is the source-mirror tree used for reference by doc tooling, not published to Mintlify).

If for some reason the daily sync is not running, that is a separate infra issue — not a documentation-content issue for this PR.

For the follow-up agent

If you are picking this issue up expecting to write documentation: please close as not_planned with a brief note referencing this rationale. Do not:

• Create a new .mdx page for the parity checker.
• Add a nav entry in docs.json.
• Update docs/concepts/* (human-approved only per AGENTS.md §1.8).
• Edit the auto-generated docs/js/, docs/rust/ files.

If a maintainer disagrees and wants an internal contributor-facing note about the parity checker added under a developer/contributing section, that is a scoping decision for a human — please ask before writing content.

https://claude.ai/code/session_019P2hrYg8sAv3XZDFoANz2M

🤖 Generated with Claude Code

https://claude.ai/code/session_019P2hrYg8sAv3XZDFoANz2M

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job

---

Review: PR #4774 — no user-facing docs required

I read AGENTS.md and analyzed PR #4774 against the documentation conventions. I concur with the issue's recommendation: no documentation change is warranted, and creating one would violate AGENTS.md.

• Read AGENTS.md folder/user-doc rules
• Verify parity checker is internal-only (not user-facing surface)
• Decide whether a docs page is warranted
• Report conclusion

Why no docs PR

PR #4774 only touches the parity checker in praisonai/_dev/parity/ — a developer-only tree. It introduces no new class, function, config, parameter, or import path in praisonaiagents/. Per AGENTS.md:

• §1.1 / §1.4 — Documentation is user-focused, sourced from real SDK exports (praisonaiagents/config/feature_configs.py, etc.). There is nothing new to document; fabricating a page would document a feature absent from the user-visible surface.
• §1.9 Folder Placement — A parity-checker page fits no valid user folder (docs/features/, docs/tools/, docs/guides/). It is not a concept (docs/concepts/ is human-only anyway), and docs/js/ + docs/rust/ are auto-generated. Adding a nav entry in docs.json would inject internal CI plumbing into user-facing navigation — a violation.
• §6 Writing Style — Docs must be agent-centric and beginner-friendly. End users never invoke the parity checker.

The behaviour delta (--check no longer reddens on pure line-number churn; update-parity-tracker.yml regenerates reports on push to main) is CI plumbing with zero impact on how users write agents, tasks, tools, memory, knowledge, or MCP.

Mirrored file — auto-syncs, no action

praisonai/_dev/parity/README.md (+4/−1) is mirrored into this repo by the daily update_repos.sh / update-repos.yml sync (AGENTS.md §1.4). It lands automatically and is not published to the Mintlify site. No manual edit needed.

Recommendation

Close this issue as not_planned. No branch or PR was created, by design — writing docs here would breach AGENTS.md. If a maintainer wants an internal contributor-facing note about the parity checker under a developer/contributing section, that is a human scoping decision.

Job run · Branch: claude/issue-3782-20260903-0942 (no changes)