Skip to content

docs: rebuild agent guidance for current architecture - #178

Merged
codeasier merged 2 commits into
mainfrom
docs/agents-current-architecture
Oct 3, 2026
Merged

codeasier merged 2 commits into
mainfrom
docs/agents-current-architecture

Conversation

@codeasier

@codeasier codeasier commented Oct 3, 2026 •

Copy link
Copy Markdown
Owner

📝 Description

Rebuild the existing AGENTS.md hierarchy from current main (7f0df45) and implementation evidence, replacing the outdated approach in #111.

  • Rewrite the root guide as navigation, development gates, runtime topology and cross-repository contracts. Give every scoped guide a visible nearest-parent link and navigable child ownership.
  • Replace generated boilerplate/empty inventories with subsystem-specific change routing, lifecycle rules and focused test maps. Keep existing guide paths stable.
  • Document the current CLI group/output split, terminal analyzer versus reusable service lifetime, borrowed cache ownership, boundary type gates, and resource-warning/coverage gates.
  • Align query guidance with v1/v2 layouts, field semantics, missing-callstack attribution, ranked windows, completeness and timeouts.
  • Cover current skill routing/preflight/identity/iteration evidence, authored/bundled parity, local evaluation descriptors and recorded baselines.
  • Recheck import backup/rollback behavior, executable fixture/LFS acceptance, package version/assets, clean-wheel acceptance and release ordering against source.

Only existing AGENTS.md files change. Product code, workflows, skills and provenance records are unchanged.

🔗 Related Issue

Supersedes #111. The previous branch is based on an older architecture (including the removed MCP surface) and is intentionally replaced with this current-main rewrite.

🧪 Testing

  • Strict validate_agents.py: 22 guides, 0 errors / 0 warnings.
  • Read-only hierarchy acceptance: every guide reachable from the root, every child linked to its nearest guide ancestor, only AGENTS.md paths changed.
  • PYTHONPATH="$PWD/src" python -m pytest tests/test_fixture_provenance.py tests/test_governance.py tests/test_release_workflow.py -q: 39 passed.
  • Skill routing links and exact boundary descriptions are also checked by existing skill contracts; the first CI run exposed three index-contract failures, addressed by restoring complete clickable SKILL.md routes and the contract-suite index.
  • PYTHONPATH="$PWD/src" python -m pytest tests/test_bundled_skills.py tests/skills -q: 148 passed after that correction.
  • Documented iteration suite descriptor validation: passed.
  • Documented target baseline aggregation: 10/10 recorded cases passed; this is deterministic grading of existing run records, not a new live-model evaluation.
  • git diff --check: passed.
  • Full product tests/builds and benchmarks were not repeated locally for this documentation-only change; the PR runs the normal full CI matrix and wheel acceptance.

✅ Checklist

  • Code follows project guidelines
  • Documentation updated
  • Changes tested locally
  • Existing AGENTS paths retained; no product behavior changes
  • No new warnings in strict documentation validation (the local environment's existing pytest-asyncio fixture-loop-scope deprecation remains)

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    Snapshot provenance decision: no-update
    Snapshot provenance no-update reason: The only changed file under src/pt_snap_cli/snapshot is AGENTS.md; this rewrites maintenance guidance from current source without changing runtime implementation, source mappings, license decisions, or provenance history.

@codeasier
codeasier merged commit 15bef33 into main Oct 3, 2026
6 checks passed
@codeasier
codeasier deleted the docs/agents-current-architecture branch October 3, 2026 19:18
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