Skip to main content

E6:S07:T112 — Planning: Spec, Tests, Implementation Plan (IPW)

Host Task: T112-install-feedback-submission-path-and-governance.md (E6:S07:T112)
Planning for: FR-079
Status: Draft

1. Specification​

1.1 Goal​

Define and implement a deterministic feedback submission path that transforms local install telemetry into safe, validated, and triage-ready maintainer input, without overlapping T111 responsibility for local event production.

1.2 Functional requirements​

  • F1: Define canonical submission artifact schema and schema versioning for outbound feedback payloads. (Source: FR-079-F1, T112 scope(1))
  • F2: Provide a deterministic user submission workflow path (CLI and documented process). (Source: FR-079-F2, T112 scope(2))
  • F3: Include provenance/correlation fields (install_run_id, framework/version context, environment summary). (Source: FR-079-F3)
  • F4: Add preflight validation (required fields, schema compatibility, payload completeness). (Source: FR-079-F4, T112 AC1)
  • F5: Define deterministic submission outcomes and diagnostics (accepted, rejected, needs-redaction, needs-more-context). (Source: FR-079-F5, T112 AC2)
  • F6: Document maintainer intake mapping from payload content to FR/BR workflows and reproducibility steps. (Source: FR-079-F6, T112 AC3)
  • F7: Explicitly enforce boundary: T111 owns local install event contract/logging; T112 owns outbound packaging/submission/governance only. (Source: FR-079-NF4, T112 AC5)

1.3 Non-functional requirements​

  • N1: Enforce privacy/redaction-safe defaults for payloads; never submit secrets.
  • N2: Deterministic retry guidance and behavior for transient submission failures.
  • N3: Keep submission UX concise while preserving sufficient forensic context for maintainers.
  • N4: Maintain compatibility with T111 output contracts and versioned schema evolution policy.

1.4 Out of scope​

  • Collecting local install telemetry itself (owned by T111/FR-078).
  • Implementing remote maintainer ticketing backend infrastructure beyond submission contract and intake guidance.
  • Closing FR/BR items automatically from submissions.

1.5 Constraints​

  • Must consume T111 artifacts as authoritative input shape.
  • Must support deterministic outcomes in offline or blocked-network scenarios with actionable local diagnostics.
  • Must preserve existing CLI logging/redaction conventions.

2. Test design​

  • T1 — Schema contract validation: Valid payload passes schema/version checks; malformed payload fails with targeted diagnostics.
  • T2 — Boundary enforcement (T111 vs T112): Submission path rejects inputs that bypass required T111 artifact structure.
  • T3 — Redaction/security preflight: Known secret patterns are detected/redacted or submission blocked with deterministic guidance.
  • T4 — Deterministic outcomes: Submission command returns one of defined terminal states with stable messaging and exit behavior.
  • T5 — Retry behavior: Transient failure yields deterministic retry instructions and does not corrupt payload state.
  • T6 — Maintainer triage mapping: Sample payload maps to reproducible FR/BR intake guidance documented in user/admin docs.
  • T7 — Compatibility evolution: Older/newer schema versions are handled with explicit compatibility diagnostics.

3. Implementation plan​

  1. Action: Define submission payload schema + version field + boundary contract to T111 artifacts.
    Deliverable: Versioned schema definition and compatibility notes.
  2. Action: Implement payload builder/packager from T111 install artifacts.
    Deliverable: Deterministic local packaging flow.
  3. Action: Implement preflight validator (schema, completeness, redaction/security checks).
    Deliverable: Validation module with actionable diagnostics.
  4. Action: Implement submission command/path and deterministic outcome handling.
    Deliverable: CLI/documented submission workflow with exit semantics.
  5. Action: Document maintainer intake mapping and triage protocol.
    Deliverable: Triage guidance for FR/BR conversion and reproduction.
  6. Action: Add tests for contract, failures, retry, and security behavior.
    Deliverable: Automated test coverage aligned to T112 AC1-AC5.

3.1 Files to create or modify​

  • cli/commands/logs.py (or dedicated feedback command module if split is cleaner)
  • cli/logging.py (shared schema helpers if needed)
  • tests/cli/ new or expanded feedback submission tests
  • docs/documentation/user-docs/ submission guidance
  • docs/project-management/kanban/fr-br/FR-079-install-feedback-submission-path-and-governance.md traceability updates
  • docs/project-management/kanban/epics/Epic-6/Story-007-adk-implementation-analysis-and-package-management/T112-install-feedback-submission-path-and-governance.md status/AC progress updates

3.2 Dependency order​

  1. Lock schema/boundary contract.
  2. Build preflight validator.
  3. Build packaging + deterministic outcome surface.
  4. Add retry/error handling.
  5. Add tests.
  6. Update docs and task/FR traceability.

4. Success / verification criteria​

  • Users can package and validate feedback payloads from T111 install artifacts (AC1).
  • Submission path returns deterministic outcomes with actionable diagnostics (AC2).
  • Maintainers can map payloads to reproducible investigation and FR/BR intake actions (AC3).
  • Redaction/security and retry behavior are covered by tests (AC4).
  • T111/T112 scope boundary is explicit in code/docs and enforced by validation (AC5).

References​