re #18 add univeros/agent-spec — AI-readable package manifests

[tonydspaniard]

Closes #18. Stacked on #23 (univeros/cli) — please review/merge #23 first, then change this PR's base to master.

Summary

univeros/agent-spec is a new sub-package that walks every framework sub-package via PHP reflection and emits deterministic Markdown manifests so AI coding agents (Claude Code, Cursor, Codex…) can understand the codebase without reading source.

• bin/altair manifest:generate → writes .agent/packages/*.md + .agent/MANIFEST.md
• bin/altair manifest:generate --check → exits 1 on drift; CI-gateable
• bin/altair manifest:show <slug> → prints one package's manifest to stdout

Output is byte-identical across runs (sorted lists, no timestamps).

What's generated per package

Each <slug>.md covers (when applicable):

Section	Source
Purpose	composer.json description (or <pkg>/.agent/purpose.md override)
Public contracts	reflection of Contracts/*Interface.php — methods, params, returns, direct constants
Concrete classes	reflection of everything outside Contracts/, Exception/, Traits/
Request attribute conventions	ATTRIBUTE_* class constants (the framework's PSR-7 convention)
Common patterns	optional <pkg>/.agent/patterns.md sidecar, split on ---
Tests as documentation	enumeration of tests/<Pkg>/*Test.php
Related packages	composer require list (excluding php/ext-*)
Stability	optional <pkg>/.agent/stability.md sidecar

Architecture

Small, focused, immutable classes — every model is readonly, every scanner is single-responsibility:

src/Altair/AgentSpec/
├── Cli/         — manifest:generate / manifest:show, PathResolver, ConsoleReporter
├── Contracts/   — PackageScannerInterface, ManifestRendererInterface, PhpFileFinderInterface
├── Exception/   — AgentSpecException, ManifestDriftException
├── Generator/   — PackageManifestGenerator, IndexGenerator, ApplicationManifestGenerator, ManifestPipeline
├── Model/       — PackageManifest, PackageDescriptor, ContractEntry, ClassEntry, AttributeConvention, MethodSignature, TestReference
├── Reflection/  — PackageScanner, ContractScanner, ConcreteClassScanner, AttributeScanner, TestFixtureScanner, SidecarReader, ClassNameExtractor, TypeStringRenderer, PhpFileFinder
├── Renderer/    — MarkdownPackageRenderer
├── Writer/      — ManifestWriter (write + check modes)
└── composer.json

CLI commands are attribute-driven (#[Command(...)], #[Option(...)]) and auto-discovered by bin/altair from the existing Altair\Cli substrate in #17.

Tests

13 tests / 41 assertions, all green. PHPStan clean on the new code.

Coverage:

• PackageScannerTest — discovery + determinism
• PackageManifestGeneratorTest — end-to-end model assembly
• MarkdownPackageRendererTest — snapshot + determinism
• IndexGeneratorTest — top-level index
• ManifestPipelineTest — write, check, byte-idempotence, drift detection
• ApplicationManifestGeneratorTest — marker-attribute grouping

Fixture package at tests/AgentSpec/Fixtures/SamplePackage/ exercises every renderable section. Snapshot lives in tests/AgentSpec/Snapshots/sample-package.md.

Out of scope (per the issue)

• LSP / IDE plugin integration (manifests are file-based; tooling can consume them)
• Hosted-docs publishing
• Multi-release versioning
• Per-application endpoint/command/event/job manifests — ApplicationManifestGenerator ships as a stub today and lights up fully once Milestone tasks univeros components version 1.0.0 #1, Queue Library #3, and Add PSR-7 FileUpload validator #5 land.

Test plan

• composer dump-autoload
• vendor/bin/phpunit tests/AgentSpec — 13/13 pass
• vendor/bin/phpstan analyse src/Altair/AgentSpec tests/AgentSpec — no errors
• bin/altair manifest:generate — produces .agent/packages/*.md + MANIFEST.md for all 18 packages
• bin/altair manifest:generate --check — exits 0 on a fresh tree, 1 after tampering with any manifest
• bin/altair manifest:show cookie — prints cookie manifest to stdout
• Manual review of the committed .agent/packages/*.md outputs