FR-078: Comprehensive install event-contract logging quality
Type: Feature Request (FR)
ID: FR-078
Submitted: 2026-04-09
Submitted By: User
Priority: CRITICAL
Severity: HIGH
Status: COMPLETE
Implementing Task: E6:S07:T111
Summary
Expand install logging from high-level operational traces to a strict event contract that captures each step's intent, action, and result with deterministic correlation IDs, so install behavior is fully reconstructable and reliable for AI Dev Kit quality hardening.
Problem Statement
Current install logging captures useful run-level and phase-level diagnostics, but it does not guarantee full forensic reconstruction of every decision and sub-step action across install execution. This creates quality risk for product hardening because maintainers cannot always derive precise root cause from existing logs.
For shippable quality, the install telemetry model must answer:
- Intent: Why was a step executed (decision context and objective)?
- Action: What exactly was done (inputs, command/operation, target, boundaries)?
- Result: What happened (status, outputs, evidence, warnings/errors, next state)?
Requirements
Functional Requirements
- FR-078-F1: Define and enforce a canonical install event schema (
intent,action,result) for all install pipeline events. - FR-078-F2: Require deterministic per-step correlation metadata (
install_run_id,step_id, parent/child relation, timestamp, actor/component). - FR-078-F3: Capture all major and sub-steps in CLI and framework-specific installers under one linked run graph (or explicitly linked child logs with guaranteed join keys).
- FR-078-F4: Record explicit decision points and branches (selected mode/backend/path, fallback/retry behavior, skip reasons, guard checks).
- FR-078-F5: Persist per-step result payloads including status, duration, exit code, validation outcomes, and normalized error categories.
- FR-078-F6: Produce a deterministic local install run artifact optimized for forensic analysis, with enough detail for maintainers to reproduce and triage.
Non-Functional Requirements
- FR-078-NF1: Maintain strong redaction and secret-safety guarantees for logs and local artifacts.
- FR-078-NF2: Keep logging overhead acceptable for normal installs with bounded storage and rotation behavior.
- FR-078-NF3: Preserve backward compatibility for existing text logs while adding a strict machine-readable event stream (JSONL/event objects).
- FR-078-NF4: Ensure partial-failure resilience: incomplete installs still emit complete event history up to the failure boundary.
Acceptance Criteria
- Running
ai-dev-kit installemits event entries where every step can be reconstructed asintent -> action -> result. - A validator (or tests) fails when required event fields are missing for any emitted step.
- Install traces across CLI + framework installers can be joined deterministically into one run timeline.
- Generated local run artifacts include enough normalized detail for maintainers' triage and reproduction workflows.
- Redaction tests confirm no secrets are emitted in event payloads.
Scope Analysis
Problem Domain: Installation telemetry, quality feedback, forensic traceability
Affected Areas:
- CLI / backend install pipeline
- Framework-specific installers
- Logging artifact docs and user guidance
- Validation/test harnesses
Estimated Complexity:
- Simple (1-3 days)
- Medium (1 week)
- Complex (2+ weeks)
- Very Complex (1+ month)
Release / verification traceability
- v0.6.7.111+1 (SemVer v0.4.721+1, E6:S07:T111, RW with
--art): Change implemented for strict install JSON event contract, CLI instrumentation,ai-dev-kit logs validate-install-log, user docs, and tests. - 2026-04-10 verification:
tests/cli/test_install_logging.py+tests/cli/test_logs_command.pypassed (11/11), including strict contract validation and redaction-focused checks. - v0.6.7.111+2 (SemVer v0.4.722+2, E6:S07:T111, RW with
--art): Verification closure release documenting FR/T111 completion and board synchronization.