Skip to main content

ICW-E6S07T111-Implementation-Plan: FR-078 Comprehensive Install Event-Contract Logging Quality

Task: E6:S07:T111
Related FR: FR-078
Host Task: T111-comprehensive-install-event-contract-logging-and-feedback-quality.md
Created: 2026-04-09

Build Plan​

  1. Schema baseline and contracts

    • Define canonical event object with required triad sections and correlation keys.
    • Define versioning and compatibility expectations for the event contract.
    • Map required/optional fields per step type.

  2. CLI orchestration instrumentation

    • Add contract event emitter at run-level and major-step boundaries.
    • Emit deterministic step IDs and parent-child relations.
    • Capture decision rationale fields at branch points.

  3. Framework installer adapter integration

    • Bridge framework-specific installers into the same event contract.
    • Ensure correlated run context is propagated to sub-installers.
    • Normalize installer-local outcomes into shared result schema.

  4. Validation and safeguards

    • Add schema completeness and joinability validators.
    • Add result normalization checks and failure-boundary tests.
    • Add redaction assertions for known sensitive paths.

  5. Documentation and operator guidance

    • Update user/operator docs for event-contract behavior.
    • Document compatibility mode and migration guidance.
    • Add troubleshooting references for common contract failures.

Deterministic Rollout Controls​

  1. Control point A - Contract first

    • Block adapter rollout until schema and required-field matrix are finalized.

  2. Control point B - Correlation integrity

    • Block merge if event graph reconstruction fails in mixed CLI/installer runs.

  3. Control point C - Redaction gate

    • Block merge on any redaction test regression.

  4. Control point D - Compatibility gate

    • Ensure existing text-log mode remains operational during transition.

  5. Control point E - Performance watch

    • Track logging overhead and gate rollout if it exceeds agreed envelope.

Integration Touchpoints​

  • CLI install orchestration and logging modules in src/
  • Framework installer scripts under packages/frameworks/
  • Install logging tests under tests/cli/
  • User documentation under docs/documentation/user-docs/
  • Task/FR traceability docs under docs/project-management/kanban/

Scope Boundary Controls​

  • Do not implement submission transport/governance flows in this task.
  • Keep any receipt/export handoff as local artifact production only.
  • Route submission-path changes to FR-079 / E6:S07:T112.

Rollback and Recovery​

  • Keep compatibility mode path available until contract rollout stabilizes.
  • If correlation or redaction regressions appear, revert to prior emitter path and preserve diagnostics for replay.
  • If performance impact exceeds threshold, disable high-volume sub-step emissions behind config while preserving mandatory step-level contract fields.

Rollback triggers:

  • Reconstruction failures for deterministic event graphs.
  • Redaction leakage in persisted artifacts.
  • Schema drift between CLI and installer adapters.
  • Material install-time overhead regression.

Exit Criteria​

  • AC1: Step/sub-step triad completeness verified.
  • AC2: Correlation and timeline reconstruction verified.
  • AC3: Missing-field failures caught by automated checks.
  • AC4: Result normalization verified across success/failure branches.
  • AC5: Local forensic artifacts support reproducible triage.
  • AC6: Redaction gates green.

Evidence Checklist​

  • Contract schema + required-field matrix documented.
  • CLI and installer emitters produce linked event graphs.
  • Validation and redaction tests are green.
  • Compatibility mode behavior verified.
  • Operator docs aligned with implemented behavior.

Handoff Notes​

This plan intentionally excludes submission/governance transport concerns, which are tracked under FR-079 / E6:S07:T112. Keep the boundary explicit to prevent responsibility bleed between local telemetry quality and feedback submission operations.