SLT.BETA.020 – Setup Questionnaire (guided configuration)

[flyingrobots]

[SLT.BETA.020] Setup Questionnaire (guided configuration)

Overview

Deliver a guided configuration experience that asks targeted questions about hosting and workflow preferences, then generates tailored Shiplog policy, trust, and CI recommendations.

References & Assets

• Figma / Design: N/A
• Product Spec (Notion / Confluence): N/A
• Related Issues / PRs: SLT.BETA.019, SLT.BETA.021
• Feature Flags / Experiments: N/A
• Other Assets: docs/features/config.md

User Story

As a team lead onboarding Shiplog, I want an interactive questionnaire that produces host-aware configuration, so that our team gets secure defaults without reading every doc upfront.

Acceptance Criteria

• TTY wizard asks questions covering host, enforcement, signing mode, threshold, auto-push, and CI preferences
• Non-interactive mode consumes answers from JSON or CLI flags
• Output includes recommended policy, trust bootstrap steps, and CI/ruleset guidance
• Wizard summaries are exportable for review or CI execution
• Dockerized tests cover representative answer flows

Definition of Done

Wizard integrated into git shiplog config, documentation updated, and automated tests validate primary flows and outputs.

Scope

In-Scope

• Questionnaire design and mapping to configuration outputs
• CLI implementation with TTY and non-interactive modes
• Documentation and examples

Out-of-Scope

• GUI wizard implementations
• Automatic repo modification beyond existing config apply path

Deliverables

• Est. Lines of Code: ~300
• Est. Blast Radius: scripts/config, docs, tests

Implementation Details

High-Level Approach

Build a question graph driving configuration templates, reuse existing plan/apply mechanics, and ensure outputs cover policy, trust, and enforcement guidance.

Affected Areas

• scripts/config
• docs/features/config.md
• README.md
• tests/config_wizard.bats

Implementation Steps

• Finalize questionnaire flows and outcomes
• Implement interactive prompts with fallback to plain text
• Support non-interactive answers via JSON file and flags
• Generate policy/trust/CI recommendations based on answers
• Update docs and add tests

Test Plan

Happy Path

• Wizard run for GitHub SaaS outputs branch namespace + ruleset guidance
• Non-interactive run produces matching plan JSON

Edge Cases

• Unsupported host triggers helpful guidance
• Re-running wizard respects previous answers when desired

Failure Cases

• Invalid answer schema surfaces descriptive validation errors

Monitoring & Success Metrics

• Wizard summary logs include chosen options and follow-up tasks

QA Sign-off Matrix

Environment	Surface	Owner	Status	Notes
Local Docker	CLI	TBD	Pending	Validated via make test

Requirements

Hard Requirements

• Generated outputs must align with hosting enforcement matrix

Soft Requirements

• Provide copy/paste snippets users can share in PRs

Runtime Requirements

• Works in non-interactive CI environments via flags/JSON

Dependencies & Approvals

• Docs review for README and config guide updates
• Security review for default trust recommendations

---

Production Notes

Priority: 4 / 5

High value onboarding improvement (P1 roadmap item).

Complexity: 4 / 5

Complex branching questionnaire with multiple output types.

Estimate: 28 - 40 hours

Covers design, implementation, docs, and thorough testing.

Risk & Rollback

• Primary Risks: Incorrect recommendations leading to insecure defaults
• Mitigations: Validate outputs against hosting matrix, review by maintainers
• Rollback / Kill Switch: Hide behind feature flag until validated

---

Additional Notes

Depends on hosting guidance (SLT.BETA.019) landing first.

[flyingrobots]

Estimate: 6 hours.

Rationale:

• Design question set and mapping to outputs (sig_mode, threshold, ref root, autoPush, workflows)
• Implement CLI: git shiplog config --interactive (TTY UI via Bosun + plain fallback)
• Emit: .shiplog/policy.json, trust bootstrap flags, suggested CI workflow and ruleset snippets
• Add non-interactive mode: accept answers via JSON/flags and print a plan
• Docs: how it works + examples; link from README and TRUST docs
• Tests: Dockerized bats covering key decision branches

Suggestion: consider splitting this into sub-tasks such as:

• Design question set and mapping to outputs (sig_mode, threshold, ref root, autoPush, workflows)
• Implement CLI: git shiplog config --interactive (TTY UI via Bosun + plain fallback)
• Emit: .shiplog/policy.json, trust bootstrap flags, suggested CI workflow and ruleset snippets