docs: update Claude docs from PR review analysis

[claude]

Summary

Weekly analysis of PR comments (2026-06-22 to 2026-07-06).
Analyzed 16 PRs with resolved review threads. Found 6 actionable insights across 2 runs.

Changes

agent_docs/conventions.md

• Keep inline code comments concise — added rule: say what is non-obvious in a single phrase; avoid restating what the code expresses.
• Timestamp field naming — all timestamp fields must use *Time suffix; *At suffixes break consistency across the SDK.
• Multi-domain responses in transform pipeline — when getById returns fields from multiple entity domains, merge multiple field maps: transformData(data, { ...PrimaryEntityMap, ...SecondaryEntityMap }).

agent_docs/rules.md

• NEVER use unexplained abbreviations/acronyms in JSDoc — spell out the full form or introduce with the expanded form first.
• NEVER use @internal on individual fields of a public interface — TypeDoc hides them from docs but IDE autocomplete still shows them; use internal type files instead.
• Propagate @experimental alongside @internal — extended the propagation rule to cover @experimental tags, which must appear on every public layer (service class, wrapper class) when the service model carries it.
• describe.skip equivalence for vitest config exclusions — excluding integration test files via env vars in vitest.integration.config.ts is functionally equivalent to describe.skip and equally prohibited; use beforeAll + throw inside the test file instead.
• Snapshot+restore pattern for mutating integration tests — when an operation has wide-reaching side effects (e.g., mark-all-read), read current state before the test and restore it in cleanup to avoid corrupting subsequent tests.

No changes

• CLAUDE.md — no relevant insights found
• Agents.md — no relevant insights found
• agent_docs/architecture.md — no relevant insights found

PRs Analyzed

PR	Title	Comments
#579	docs(governance): mark governance service and methods as experimental	2 threads
#495	feat(samples): add document-validation-app sample	13 threads
#541	docs: sample GitHub Action for coded app CI/CD	20 threads
#552	ci: add weekly coverage run against main branch	2 threads
#514	feat(notifications): delete flows (PR 3/7)	3 threads
#572	fix(data-fabric): stop requiring referenceEntityId/referenceFieldId for FILE fields	1 thread
#573	chore: bump version to 1.5.1	0 threads
#513	feat(notifications): mark-read flows (PR 2/7)	6 threads
#560	feat(traces): add agentic governance traces and summary methods	many threads
#571	test(data-fabric): make ApiClient mocks constructable for vitest 4	0 threads
#570	test(notifications): make ApiClient mock constructable for vitest 4	0 threads
#473	feat: add Data Fabric roles and directory services	many threads
#550	test+deps: bump vitest to 4.x	1 thread
#553	feat(maestro): add retry to process instances	6 threads
#512	feat(notifications): foundation + getAll (PR 1/7)	many threads
#548	fix: rewrite SDK field names in OData options for remaining services	many threads

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud