docs(installer): define module selection contract

Author: Dicklesworthstone

.beads/issues.jsonl

@@ -850,7 +850,7 @@
 {"id":"bd-mg9","title":"Add --resume and --force-reinstall CLI flags","description":"# Task: Add --resume and --force-reinstall CLI flags\n\n## Context\nPart of EPIC: Phase-Granular Progress Persistence (agentic_coding_flywheel_setup-5uu)\n\n## What to Do\nAdd new command-line flags to install.sh:\n\n### --resume\n- Explicit intent to resume from checkpoint\n- Default behavior when state.json exists\n- Skips resume confirmation prompt in non-interactive mode\n\n### --force-reinstall\n- Ignores existing state.json\n- Starts fresh installation from phase 1\n- Clears state file before starting\n\n### --reset-state\n- Deletes state.json and exits\n- For debugging/recovery purposes\n- Does not run installation\n\n## Acceptance Criteria\n- Flags parsed correctly in argument handling\n- --force-reinstall clears state before install\n- --resume is default when state exists\n- --reset-state only removes state and exits\n- Help text updated with new flags\n\n## Implementation Notes\nUpdate the existing flag parsing loop in install.sh around line 35-43\n\n## Files to Modify\n- install.sh: Argument parsing and help text","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-21T17:42:42.685179Z","updated_at":"2025-12-21T19:45:28.771417Z","closed_at":"2025-12-21T19:45:28.771417Z","close_reason":"CLI flags already implemented: --resume, --force-reinstall, --reset-state, --interactive. Added export statements to fix shellcheck warnings and ensure state.sh can access the flags.","source_repo":".","compaction_level":0,"original_size":0,"dependencies":[{"issue_id":"bd-mg9","depends_on_id":"bd-yaj","type":"blocks","created_at":"2025-12-21T17:47:28.129688Z","created_by":"daemon","metadata":"{}","thread_id":""}]}
 {"id":"bd-mhmdd","title":"Deep code audit & fixes","status":"closed","priority":1,"issue_type":"task","created_at":"2026-02-04T05:11:08.707179681Z","created_by":"ubuntu","updated_at":"2026-02-04T05:19:45.700648014Z","closed_at":"2026-02-04T05:19:45.700625381Z","close_reason":"Completed","source_repo":".","compaction_level":0,"original_size":0}
 {"id":"bd-mirb","title":"Fix ubuntu upgrade unit tests for EOL skipping","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-29T00:58:00.761417Z","updated_at":"2025-12-29T00:58:07.954248Z","closed_at":"2025-12-29T00:58:07.954248Z","close_reason":"Completed","source_repo":".","compaction_level":0,"original_size":0}
-{"id":"bd-mitxy","title":"Design shared module selection resolver contract","description":"## What\nDefine the exact selection contract shared by `install.sh`, generated manifest metadata, the wizard command builder, and any future TUI selector.\n\n## Why\nExisting selection flags are useful for maintainers, but beginner-safe selection needs explicit rules for required modules, dependency expansion, conflicts, optional groups, and why a module was included or skipped.\n\n## Approach\n- Inventory current `--only`, `--skip`, `--print-plan`, and generated metadata behavior.\n- Specify profile names, module groups, dependency expansion, forced-required modules, and error messages.\n- Include examples for safe, vibe, minimal, cloud-only, stack-only, and invalid selections.\n\n## Risks\nDivergence between website and installer would be worse than no selector. Treat the resolver contract as a shared test target.\n\n## Success Criteria\nA future implementer can write resolver tests directly from this bead without consulting the original planning discussion.\n\n## Acceptance Criteria\n- Scope in this bead is implemented or documented without hidden compatibility shims.\n- Unit, script, Playwright, VM, or fixture tests are added according to the affected surface; skipped live/provider tests name the required environment.\n- Logs and artifacts are detailed enough for support or CI triage and redact credentials, tokens, IPs, and provider-sensitive values where applicable.\n- Website, installer, generated-manifest, onboarding, support-bundle, and docs surfaces stay consistent when the change touches more than one of them.\n- Required quality gates for touched surfaces pass, including shellcheck for Bash, Bun type-check/lint/build for web work, `br lint`, dependency-cycle checks, and `ubs` before commit.","acceptance_criteria":"- Scope in the description is implemented or documented with no hidden compatibility shim.\n- Unit, script, Playwright, VM, or fixture tests are added according to the affected surface; skipped live/provider tests must name the required environment.\n- Logs and artifacts are detailed enough for support or CI triage and redact credentials, tokens, IPs, and provider-sensitive values where applicable.\n- Website, installer, generated-manifest, onboarding, support-bundle, and docs surfaces stay consistent when the change touches more than one of them.\n- Required quality gates for touched surfaces pass, including shellcheck for Bash, Bun type-check/lint/build for web work, `br lint`, dependency-cycle checks, and `ubs` before commit.","notes":"## Refinement Safety Notes\n- Preserve verified-installer checksum discipline; selection or generation work must not create any unverified install path.\n- Required core modules must be locked or explicitly explained before any skip is accepted.\n- Prefer dry-run/plan output before mutation, and include tests for invalid input, required-module refusal, and no hidden side effects.\n- Do not add compatibility shims for deprecated option names; update the canonical path directly.","status":"open","priority":1,"issue_type":"task","created_at":"2026-05-08T19:47:46.431412065Z","created_by":"ubuntu","updated_at":"2026-05-08T20:07:59.275252664Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["installer","module-selection","tests","web"]}
+{"id":"bd-mitxy","title":"Design shared module selection resolver contract","description":"## What\nDefine the exact selection contract shared by `install.sh`, generated manifest metadata, the wizard command builder, and any future TUI selector.\n\n## Why\nExisting selection flags are useful for maintainers, but beginner-safe selection needs explicit rules for required modules, dependency expansion, conflicts, optional groups, and why a module was included or skipped.\n\n## Approach\n- Inventory current `--only`, `--skip`, `--print-plan`, and generated metadata behavior.\n- Specify profile names, module groups, dependency expansion, forced-required modules, and error messages.\n- Include examples for safe, vibe, minimal, cloud-only, stack-only, and invalid selections.\n\n## Risks\nDivergence between website and installer would be worse than no selector. Treat the resolver contract as a shared test target.\n\n## Success Criteria\nA future implementer can write resolver tests directly from this bead without consulting the original planning discussion.\n\n## Acceptance Criteria\n- Scope in this bead is implemented or documented without hidden compatibility shims.\n- Unit, script, Playwright, VM, or fixture tests are added according to the affected surface; skipped live/provider tests name the required environment.\n- Logs and artifacts are detailed enough for support or CI triage and redact credentials, tokens, IPs, and provider-sensitive values where applicable.\n- Website, installer, generated-manifest, onboarding, support-bundle, and docs surfaces stay consistent when the change touches more than one of them.\n- Required quality gates for touched surfaces pass, including shellcheck for Bash, Bun type-check/lint/build for web work, `br lint`, dependency-cycle checks, and `ubs` before commit.","acceptance_criteria":"- Scope in the description is implemented or documented with no hidden compatibility shim.\n- Unit, script, Playwright, VM, or fixture tests are added according to the affected surface; skipped live/provider tests must name the required environment.\n- Logs and artifacts are detailed enough for support or CI triage and redact credentials, tokens, IPs, and provider-sensitive values where applicable.\n- Website, installer, generated-manifest, onboarding, support-bundle, and docs surfaces stay consistent when the change touches more than one of them.\n- Required quality gates for touched surfaces pass, including shellcheck for Bash, Bun type-check/lint/build for web work, `br lint`, dependency-cycle checks, and `ubs` before commit.","notes":"## Refinement Safety Notes\n- Preserve verified-installer checksum discipline; selection or generation work must not create any unverified install path.\n- Required core modules must be locked or explicitly explained before any skip is accepted.\n- Prefer dry-run/plan output before mutation, and include tests for invalid input, required-module refusal, and no hidden side effects.\n- Do not add compatibility shims for deprecated option names; update the canonical path directly.","status":"closed","priority":1,"issue_type":"task","created_at":"2026-05-08T19:47:46.431412065Z","created_by":"ubuntu","updated_at":"2026-05-08T20:20:38.037564030Z","closed_at":"2026-05-08T20:20:38.037320023Z","close_reason":"Documented shared module selection resolver contract with profile mappings, dependency semantics, errors, and fixture requirements","source_repo":".","compaction_level":0,"original_size":0,"labels":["installer","module-selection","tests","web"]}
 {"id":"bd-mjt","title":"EPIC: Manifest-Driven Installer Integration (Single Source of Truth)","description":"## Why this epic exists\nToday ACFS effectively has **two universes**:\n- **Universe A (reference only):** `acfs.manifest.yaml` → generator → `scripts/generated/*`\n- **Universe B (reality):** `install.sh` contains hand-maintained install logic\n\nThat split creates ongoing drift, duplicated effort, and bugs that only show up on real machines.\n\nThis epic makes the manifest the *actual* single source of truth for what gets installed, how it’s installed, and how it’s verified.\n\n## Goal (end state)\n- `acfs.manifest.yaml` is canonical for:\n  - selection (defaults / only / skip)\n  - ordering (phase + deps)\n  - install behavior (run_as, verified upstream installers, optional)\n  - verification (doctor existence checks)\n- `scripts/generated/*` is **the** module-install implementation used by the installer.\n- `install.sh` becomes a thin orchestrator:\n  - bootstraps a self-consistent repo snapshot in `curl|bash` mode (single archive)\n  - sources libs + generated installers (local files only)\n  - handles orchestration-only steps (user normalization, phase framing, UX)\n  - computes selection once (dependency closure) and then executes deterministically\n\n## Non-goals\n- Rewriting the installer in TypeScript / requiring Bun before base packages.\n- Supporting non-Ubuntu targets.\n- Turning ACFS into an “open contributor” project (internal-only posture remains).\n\n## Security & reliability invariants\n- No `source <(curl ...)`.\n- Verified installers only: remote scripts must be HTTPS + SHA256 verified via `checksums.yaml`.\n- Generated scripts are libraries: safe to source, no side effects at import.\n- No “set -e landmines”: generated module functions must explicitly catch/handle failures so optional modules cannot kill the whole run.\n- `curl|bash` bootstrap must be atomic and validated (`bash -n` before sourcing) with a coherence check (manifest SHA).\n\n## UX invariants\n- `--only` should be safe by default (dependency closure).\n- `--skip` must fail early if it creates a broken plan (skipping required deps).\n- Defaults must be explicit (`enabled_by_default`) so we can add tools without surprising beginners.\n\n## Deliverables\n- Manifest schema vNext (category/tags/defaults/run_as/verified_installer/deps)\n- Deterministic `manifest_index.sh` (and optional JSON) generated from manifest\n- install.sh refactor: archive bootstrap + manifest-driven selection + generated installer execution\n- Test coverage: offline “simulate curl|bash bootstrap”, selection safety tests, existing Docker integration tests\n- Docs: internal maintainer workflow + user-facing flag documentation (integrated into existing README sections)\n\n## Coordination with existing open epics\nThis epic touches `install.sh`, but must remain compatible with:\n- Preflight validation\n- State/resume + phase wrappers\n- Structured error reporting / try_step\n- Checksum recovery UX\n\nThose efforts should remain orchestrator/lib-owned so they survive migration.\n","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-21T18:47:13.453531Z","updated_at":"2025-12-21T22:27:42.036795Z","closed_at":"2025-12-21T22:27:42.036795Z","close_reason":"All 7 phases complete: spec freeze, gap analysis, schema vNext, generator enhancements, install.sh refactor, testing/CI, documentation. Manifest is now the single source of truth.","source_repo":".","compaction_level":0,"original_size":0,"labels":["architecture","installer","manifest"],"dependencies":[{"issue_id":"bd-mjt","depends_on_id":"bd-0ok","type":"related","created_at":"2025-12-21T18:49:50.301283Z","created_by":"daemon","metadata":"{}","thread_id":""},{"issue_id":"bd-mjt","depends_on_id":"bd-5uu","type":"related","created_at":"2025-12-21T18:49:50.450417Z","created_by":"daemon","metadata":"{}","thread_id":""},{"issue_id":"bd-mjt","depends_on_id":"bd-fkf","type":"related","created_at":"2025-12-21T18:49:50.596866Z","created_by":"daemon","metadata":"{}","thread_id":""},{"issue_id":"bd-mjt","depends_on_id":"bd-t9i","type":"related","created_at":"2025-12-21T18:49:50.879617Z","created_by":"daemon","metadata":"{}","thread_id":""},{"issue_id":"bd-mjt","depends_on_id":"bd-tx7","type":"related","created_at":"2025-12-21T18:49:50.737149Z","created_by":"daemon","metadata":"{}","thread_id":""}]}
 {"id":"bd-mjt.1","title":"Phase 0: Spec freeze + cross-epic harmonization","description":"## Purpose\nLock down the behavioral contracts (selection semantics, bootstrap invariants, module runtime contract) so implementation work is deterministic and doesn’t churn.\n\n## Why this matters\nWe have multiple open reliability epics that touch `install.sh`. If we don’t freeze contracts now, we’ll create repeated merge conflicts and inconsistent UX.\n\n## Outputs\n- A crisp, testable spec for:\n  - selection + dependency closure (inputs/outputs/error semantics)\n  - tags/categories/defaults strategy\n  - curl|bash bootstrap contract + env vars\n  - generated module function contract (run_as + strict-mode safety)\n\n## Acceptance criteria\n- Decisions recorded in `PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md`.\n- A concrete “golden path” CLI story that matches the wizard flows.\n- A minimal “expert debugging” story (`--no-deps`, `--print-plan`).\n","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-21T18:47:13.621348Z","updated_at":"2025-12-21T20:44:52.169492Z","closed_at":"2025-12-21T20:44:52.169492Z","close_reason":"Added golden path CLI stories (Stories 1-5) and expert debugging stories (D1-D5) to PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md. Phase 0 spec freeze complete - unblocks mjt.1.2","source_repo":".","compaction_level":0,"original_size":0,"labels":["architecture","manifest","planning"],"dependencies":[{"issue_id":"bd-mjt.1","depends_on_id":"bd-mjt","type":"parent-child","created_at":"2025-12-21T18:47:13.621726Z","created_by":"daemon","metadata":"{}","thread_id":""}]}
 {"id":"bd-mjt.1.1","title":"Define module taxonomy (categories/tags/defaults)","description":"## Goal\nDefine a coherent taxonomy that supports:\n- human comprehension (website wizard, docs)\n- deterministic generation (file layout)\n- selection and filtering (defaults, legacy skip flags)\n\n## Decisions to make\n- Canonical `category` set (e.g., base/shell/cli/lang/agents/cloud/stack/acfs)\n- Canonical `tags` set (e.g., lang,runtime,cloud,db,secrets,agent,ux,critical,recommended)\n- Default install policy:\n  - what is `enabled_by_default: true`\n  - what is opt-in (enabled_by_default false)\n\n## Constraints\n- Must preserve existing wizard flows.\n- Must keep “beginner default install” stable and unsurprising.\n\n## Output\n- A short table in the plan doc mapping:\n  - legacy flags → tags/modules\n  - category → wizard step(s)\n","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-21T18:49:19.143465Z","updated_at":"2025-12-21T20:38:56.364844Z","closed_at":"2025-12-21T20:38:56.364844Z","close_reason":"Documented module taxonomy in PLAN_TO_HAVE_SINGLE_SOURCE_OF_TRUTH_MANIFEST.md. Defined 8 canonical categories, 10 tags, enabled_by_default policy, legacy flag mappings, and category→wizard step mappings.","source_repo":".","compaction_level":0,"original_size":0,"labels":["manifest","planning"],"dependencies":[{"issue_id":"bd-mjt.1.1","depends_on_id":"bd-mjt.1","type":"parent-child","created_at":"2025-12-21T18:49:19.148024Z","created_by":"daemon","metadata":"{}","thread_id":""},{"issue_id":"bd-mjt.1.1","depends_on_id":"bd-v8a","type":"blocks","created_at":"2025-12-21T19:09:58.391953Z","created_by":"daemon","metadata":"{}","thread_id":""}]}