feat(reports): unified top-level meta (factory + central save hook), refs #917

[ootakazuhiko]

Update: Wave 2–3 meta unification & CI-aware shape

• Factory (src/utils/meta-factory.ts)
  • buildReportMeta({ envOverride? }) → returns invariant shape with defaults
  • Sources: env/CI > git > defaults ('unknown'/null), createdAt now
  • CI-safe: handles missing git/CI gracefully
• Central injection
  • QualityGateRunner.saveReport() enriches report at write-time
  • Bench/Req2Run now also use the same factory for consistency
• Re-export
  • src/index.ts re-exports buildReportMeta for consumers
• Tests
  • tests/utils/meta-factory.test.ts: env on/off, git fallback, shape invariants
  • tests/quality/quality-gate-runner.meta.test.ts: verifies meta presence at save-time
• Docs
  • docs/quality/report-meta.md: field definitions, env precedence, example

Before/After (Quality Gate report excerpt)
Before:
{
"timestamp": "...",
"environment": "testing",
"overallScore": 100,
"results": [...]
}

After:
{
"timestamp": "...",
"environment": "testing",
"overallScore": 100,
"results": [...],
"meta": {
"agent": { "name": "unknown", "version": "1.0.0" },
"model": { "provider": null, "name": null },
"traceId": null,
"iteration": 0,
"runId": null,
"commitSha": "abcdef...",
"branch": "feat/917-meta",
"environment": "local",
"createdAt": "2025-09-19T...Z"
}
}

Notes

• Additive-only: no schema breaks
• Unified factory ensures constant shape even with missing env/CI
• Consumers can import { buildReportMeta } from 'ae-framework'

---

CI Policy (internal vs external)

• Internal (in-scope): Changes in this PR (meta-factory, central save hook, bench/req2run adoption, docs, targeted tests). Action: keep green locally; fix PR-caused regressions.
• External (out-of-scope): Pre-existing or unrelated CI/test failures. Action: will be handled in a separate PR.

Precedence Summary

• git/CI → env → defaults. See docs/quality/report-meta.md.

[github-actions]

❓ Code Generation Drift Detection

Status:
Regeneration needed: No

---

Automated by AE-Framework Codegen

[github-actions]

Quality Summary

• Adapters:

• Formal: n/a

• Replay: 3 events, 0 violations

• Trace IDs: t-1

[github-actions]

❓ Code Generation Drift Detection

Status:
Regeneration needed: No

---

Automated by AE-Framework Codegen

[github-actions]

❓ Code Generation Drift Detection

Status:
Regeneration needed: No

---

Automated by AE-Framework Codegen

[github-actions]

❓ Code Generation Drift Detection

Status:
Regeneration needed: No

---

Automated by AE-Framework Codegen

[ootakazuhiko]

Wave 2–3 plan to reach a good stopping point:\n\n- [ ] Implement src/utils/meta-factory.ts (buildReportMeta): git(commitSha/branch), env(AE_AGENT_NAME/AE_AGENT_MODEL/TRACE_ID/RUN_ID/ENVIRONMENT), createdAt(ISO), iteration; keep shape constant.\n- [ ] Apply factory at a central save hook so all reports include meta; consider artifacts/progress/summary.json if present (minimal change).\n- [ ] Tests: factory unit (env/git present/absent, CI fallback), save-path presence/shape checks.\n- [ ] Docs: docs/quality/report-meta.md (definition, precedence, CI filling, examples). Re-export factory from index as needed.\n- [ ] CI: address failures caused by this PR only; global issues go to separate PRs.\n\nUpdate PR description with before/after JSON and precedence notes when done.