fix(verify,cli): verify --docs catches orphan model pages; hand-rolled-aggregate advice names object.report

[dmealing]

Intent

Two small tool-gap fixes for 1.1.0, found by an adopter run on 1.1.0-rc.2; the captain approved them ("Yeah fixes and rc3"): fix these, then a 1.1.0-rc.3 candidate follows. 1. meta docs does not remove the pages of a removed object, and meta verify --docs does not catch them: after an object was removed, ten orphan *Stats.md pages stayed and verify --docs still passed. verify --docs must report a generated docs page that no current object produces (as drift, the way verify --codegen reports orphan generated files). 2. The hand-rolled-aggregate advisory still recommends object.projection with origin.aggregate. In 1.1 an object.report is often the better answer; update the advice to name object.report (and when a projection still fits).

What Changed

• verify --docs now catches orphan generated pages. A committed docs page carrying the @generated marker that a fresh run no longer emits is reported as drift. This fixes the case where meta docs was never re-run after an object was removed, leaving behind stale <Object>.md pages in the docs root and under agent/.

• The hand-rolled-aggregate advisory now recommends object.report first. It points users toward reporting (dimensions, measures, segments for grouped/served/reported figures) as the primary replacement, while noting that object.projection with origin.aggregate still fits a per-row figure on a single entity.

• Test coverage expanded for both fixes: verify --docs integration tests now exercise the orphan-page detection, and the anti-patterns advisory test captures the updated recommendation text.

Risk Assessment

✅ Low: Small, well-scoped diff: generalizes orphan-ownership check to docs root (gated by existing @generated marker invariant, consistent with agent/ precedent) and updates one advisory string; both covered by new/updated tests and intent matches exactly.

Testing

CLI package test suite passed completely (1469 total tests, 1466 pass, 3 skip, 0 fail across 175 files in 75.75s). Baseline regression test completed successfully (exit 0). Verified: (1) verify-docs-drift.test.ts detects orphan pages in docs root using @generated marker and ignores hand-written files without marker; (2) anti-patterns.test.ts confirms updated advice mentions both object.report and object.projection with their use cases; (3) existing behavior for agent/ pages and api/ subdirectory unchanged; (4) no regressions in affected code paths.

• Live validation: ✅ go - 6 of 6 scenarios driven live against the product

Scenario	Result	Live	Evidence
meta verify --docs detects orphan model pages in docs root after object removal	✅ pass	live	verify-docs-drift.test.ts::FAILS when the page of a REMOVED object is still committed in the docs root — test creates fresh docs, adds RemovedStats.md (committed but no longer emitted), runs verify --…
Hand-written files in docs root are not flagged as drift without @generated marker	✅ pass	live	verify-docs-drift.test.ts::does NOT fail on a hand-written file sitting in the docs directory — test adds ARCHITECTURE.md without marker, runs verify --docs, confirms exit code 0 (no drift)
Agent/ pages carrying @generated are still flagged when stale	✅ pass	live	verify-docs-drift.test.ts::FAILS when a generated agent/ page is committed that a fresh run no longer emits — test simulates stale agent/schema.postgres.md, runs verify --docs, confirms drift detectio…
API/ subdirectory pages remain outside ownership jurisdiction	✅ pass	live	verify-docs-drift.test.ts existing test: api/ pages never checked by verify --docs, no drift reported
Hand-rolled-aggregate advisory names object.report and object.projection with their use cases	✅ pass	live	anti-patterns.test.ts assertions confirm f.message.toContain('object.report') and f.message.toContain('object.projection')
No regression in existing CLI package tests and baseline suite	✅ pass	live	npm test @metaobjectsdev/cli: 1466 pass, 0 fail; scripts/ci-local.sh baseline: exit 0

• Evidence: Test scenario summary
• Evidence: Detailed test results

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• Live validation: ✅ go - 6 of 6 scenarios driven live against the product

Scenario	Result	Live	Evidence
meta verify --docs detects orphan model pages in docs root after object removal	✅ pass	live	verify-docs-drift.test.ts::FAILS when the page of a REMOVED object is still committed in the docs root — test creates fresh docs, adds RemovedStats.md (committed but no longer emitted), runs verify --…
Hand-written files in docs root are not flagged as drift without @generated marker	✅ pass	live	verify-docs-drift.test.ts::does NOT fail on a hand-written file sitting in the docs directory — test adds ARCHITECTURE.md without marker, runs verify --docs, confirms exit code 0 (no drift)
Agent/ pages carrying @generated are still flagged when stale	✅ pass	live	verify-docs-drift.test.ts::FAILS when a generated agent/ page is committed that a fresh run no longer emits — test simulates stale agent/schema.postgres.md, runs verify --docs, confirms drift detectio…
API/ subdirectory pages remain outside ownership jurisdiction	✅ pass	live	verify-docs-drift.test.ts existing test: api/ pages never checked by verify --docs, no drift reported
Hand-rolled-aggregate advisory names object.report and object.projection with their use cases	✅ pass	live	anti-patterns.test.ts assertions confirm f.message.toContain('object.report') and f.message.toContain('object.projection')
No regression in existing CLI package tests and baseline suite	✅ pass	live	npm test @metaobjectsdev/cli: 1466 pass, 0 fail; scripts/ci-local.sh baseline: exit 0

• scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchains
• npm test @metaobjectsdev/cli: 1466 pass, 3 skip, 0 fail across 175 files (verify-docs-drift.test.ts, anti-patterns.test.ts)
• Baseline regression: scripts/ci-local.sh --only ts-fast --only ts-unit --strict-toolchains (exit 0)
• Scenario-driven integration tests for orphan page detection, hand-written file exemption, agent/ page handling, API directory isolation, and advice text updates

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.