Files
canina/specs/corporate-execution-observability/monthly-plan-slice.md
T
2026-10-30 12:28:51 +00:00

61 lines
7.5 KiB
Markdown

# Persisted dated monthly plan — local implementation receipt
Base: `18094f91a6babdd8e08e7b294e18557de9778d59` (official develop, verified 2026-10-30).
## Bounded acceptance audit
- Existing `CorporateService.research()` and `roadmap()` persist research sources, roadmap and goals, but the roadmap contains aggregate counts rather than a dated execution calendar.
- Existing `scripts/corporate_runtime.py:fanout()` creates only RESEARCH inventory tasks. Existing department `plan_day()` reports unresolved audit findings in `dailyNew`; this is not a daily article calendar.
- Existing task goal relationship and event JSON payload support a no-schema slice. No schema design/apply is needed for this implementation.
## Implemented contract
`POST /api/admin/hermes/monthly-plans` uses existing controller authentication and required Idempotency-Key. Body: `roadmapId`, `month` (YYYY-MM), `dailyArticles` and `needs`.
Every calendar day has exactly one BLOG_NEW entry. Entries carry title, description, department, priority, goalId, actionType, dueCycle (YYYY-MM-DD) and sourceIds. Source IDs must exist in the stored roadmap research; goal and department must belong to that roadmap. Missing, duplicate or impossible dates fail closed. Needs use BLOG_UPDATE, CATALOG_ENRICH, WIKI_ENRICH or ENGINEERING and additionally require target and reason. Needs never satisfy daily NEW coverage and empty needs are allowed rather than fabricating quotas.
The backend transaction creates real task rows and PLANNED events containing research/roadmap/goal/source/date lineage. A roadmap/month advisory lock prevents duplicate plans across keys/actors. Existing operation replay returns the original response for exact same-key retries; conflicting payloads fail. Injection coverage proves partial writes roll back.
`GET /api/admin/hermes/monthly-plans/:roadmapId?month=YYYY-MM` reads persisted tasks with their PLANNED lineage. Claim eligibility gates only planned tasks by matching dueCycle and UTC day; future planned work is not immediately claimable. Legacy undated directives retain existing behavior.
Manual CLI `plan-month manifest.json` checkpoints the exact request before POST; `read-plan roadmap-id YYYY-MM` performs authenticated readback. No schedule, worker, publisher or claim is invoked by either command. Preserve stable mutation keys and read back after ambiguous transmission before any explicit retry.
## Real local verification
Evidence directory: `/opt/data/content-maintenance/corporate-plan-evidence-20261030/`.
- Backend RED: `backend-red.log`; readback RED: `backend-readback-red.log`.
- Final focused PostgreSQL integration/policy GREEN: 2 suites, 24 tests, `backend-focused-final2.log`. Expected injected database failure is logged by the rollback test; suite passes.
- Backend TypeScript build: exit 0, `backend-build-final2.log`.
- Full backend attempt: 104 suites passed, 1 failed, 2 skipped; 942 tests passed, 1 failed, 3 skipped. `backend-full-final.log`. Blocker is SEO worker HTTP ingestion replay returning 409 (reproduced twice); not claimed fully green.
- Manual CLI checkpoint regression RED: missing monthly_plan AttributeError, `runtime-red.log`; all corporate Python suites GREEN: 19 tests, `runtime-green.log`.
- `git diff --check`: clean.
## Safety and next dependencies
No commit, push, deployment, live business-data mutation, migration, main, cron, Hermes config or admin approval module change. MANUAL_DORMANT remains unchanged. This is locally implemented planning, not enterprise DONE or live acceptance.
Next: parent-owned single develop push and Stage CI; authenticated Stage plan creation/readback with real approved research; then implement action-specific execution/evidence/independent QA for planned tasks, public outcome readback, and explicit scheduling authorization only after those gates. Legacy department report's QA_REVIEW/TEST mismatch remains separate followup; it is not a monthly article planner.
## Integrated review and regression repair (2026-10-30)
Acceptance: preserve exact replay and reject changed numeric evidence, without tolerances, skipped gates, DDL or live writes. Preserve plan transactions, full calendar, daily BLOG_NEW versus separate needs, source lineage, and actor-independent roadmap/month uniqueness.
Independent source review confirmed transaction/lineage/calendar/guard design. The graph SHA256 is `6a73473cee9e207543fdeeb668bea544f766200a1b16b8a3a9ce18d4e42e51af`; its revision is unbound and it lacks planner nodes, so it remains navigation only. UUID case normalization defect was reproduced RED (`review-uppercase-red.log`) and fixed: accepted uppercase roadmap/goal/source IDs now normalize before lineage, hashing, lock scope and readback. The API integration test sends uppercase IDs and GETs uppercase roadmap ID. Future claim fixtures moved to leap month 2996-02, preserving trigger rollback checks.
Baseline full command on clean detached `18094f91` with the identical resolved node_modules and unchanged package-lock reproduced the SEO HTTP 409: 104 pass / 1 fail / 2 skipped suites, 933 pass / 1 fail / 3 skipped tests (`review-baseline-full.log`). The same HTTP test fails independently (`review-baseline-worker.log`). This is a pre-existing production numeric replay defect, not a monthly-plan regression. Diagnostic RED logs show 3.1818181818181817 returning as 3.181818181818182 and 18.333333333333332 as 18.33333333333333; nested JSON changes too. Prisma numeric transport loses exact double input. The repair uses text-bound PostgreSQL casts for Float and JSON writes atomically with create, and native PostgreSQL equality for replay. It does not use epsilon comparison. Concurrent real-PG numeric replay and single-ULP numeric/provenance changes are covered; changed evidence still returns 409. Previously rounded rows are not rewritten or silently accepted.
Final local results (all logs in the evidence directory above):
- `review-full-final.log`: 105 suites passed, 2 existing opt-in suites skipped; 944 tests passed, 3 existing opt-in tests skipped. Fresh disposable SEO/publication/corporate PostgreSQL clusters, stopped by the runner. No new skips.
- `review-focused-final.log`: monthly policy/API and SEO real worker HTTP/service regressions, exit 0.
- `review-build-final.log`: `npm run build`, exit 0.
- `review-runtime-all-final.log`: all corporate Python unittest discovery, exit 0.
- Expected injected database ERROR during rollback coverage is not a failing suite.
Review limitations: manual checkpoint submission has no dedicated monthly-plan replay subcommand (use stable original request/key and readback); action-specific consumers remain deferred/dormant. No Stage behavior or production identity is established by local JWT/PG tests. Parent must freeze the integrated commit, use official Stage CI, verify MANUAL_DORMANT and cron disconnection, and read back approved dated plan/actionType/lineage before calling Stage accepted. No commit/push/deploy performed by this worker.
## Repository recovery
Durable valid clone: `/opt/data/content-maintenance/corporate-durable-20261030`.
Broken original `/opt/data/content-maintenance/engine/worktree-concurrency-tdd` was not reset, cleaned or deleted. The missing scratch Git metadata was not recreated or rewritten. 332 source/spec/graph evidence files were copied with SHA256 manifest at `/opt/data/content-maintenance/recovery-evidence-20261030/manifest.json`; untracked owned specs/.specify were preserved without replacing tracked current develop files. Original graph and stamps remain external evidence. The recovered graph lacks corporate service/planner nodes, so source/tests, not graph inference, ground this slice.