docs(offline): define artifact pack trust policy

Author: Dicklesworthstone

.beads/issues.jsonl

@@ -508,7 +508,7 @@
 {"id":"bd-8mv","title":"Add --strict flag for legacy checksum behavior","description":"# Task: Add --strict flag for legacy checksum behavior\n\n## Context\nPart of EPIC: Checkpoint-Based Checksum Recovery (agentic_coding_flywheel_setup-tx7)\n\n## What to Do\nAdd --strict flag that restores the original behavior where ANY checksum mismatch aborts installation.\n\n### Behavior\n- Without --strict (default): Use new recovery flow\n- With --strict: All tools treated as critical, any mismatch aborts\n\n### Use Cases\n- Security-conscious users who want no exceptions\n- CI/CD environments where reproducibility matters\n- Auditing/compliance scenarios\n\n## Acceptance Criteria\n- --strict flag parsed in argument handling\n- When set, all tools treated as critical\n- Help text documents the flag\n- Default behavior is recovery flow\n\n## Files to Modify\n- install.sh: Argument parsing, pass flag to security functions","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-21T17:44:39.830135Z","updated_at":"2025-12-21T20:04:39.956587Z","closed_at":"2025-12-21T20:04:39.956587Z","close_reason":"Added --strict flag to install.sh that sets ACFS_STRICT_MODE=true. When enabled, all tools are treated as CRITICAL and any checksum mismatch aborts installation. Updated header documentation.","source_repo":".","compaction_level":0,"original_size":0,"dependencies":[{"issue_id":"bd-8mv","depends_on_id":"bd-v8a","type":"blocks","created_at":"2025-12-21T17:47:33.579339Z","created_by":"daemon","metadata":"{}","thread_id":""}]}
 {"id":"bd-8pkn","title":"Fix contract tests: stub _acfs_is_interactive","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-22T22:03:32.947459Z","updated_at":"2025-12-22T22:04:25.346479Z","closed_at":"2025-12-22T22:04:25.346479Z","close_reason":"Completed: test stubs now include _acfs_is_interactive required by contract","source_repo":".","compaction_level":0,"original_size":0}
 {"id":"bd-8qd3d","title":"Research optional systemd resource isolation profiles for agent CLIs","description":"## Parent program\n`bd-nlb8w`; next-best idea from the idea-wizard expansion; depends on capacity model `bd-e63fl`.\n\n## What\nResearch and design optional systemd/user-slice or shell-wrapper resource isolation profiles for agent CLIs on large ACFS hosts. The output should say whether ACFS should expose recommended CPU/memory weights or limits for Claude, Codex, Gemini, RCH, and support daemons.\n\n## Why\nOn 64+ core hosts, resource contention can still make the system feel broken if one class of process consumes all CPU, RAM, or I/O. Optional isolation can improve responsiveness without reducing user control.\n\n## How\nStudy current ACFS services/user service setup, systemd availability on target Ubuntu, and agent launch aliases. Prefer opt-in profiles and documented recommendations before enforcement.\n\n## Risks\nHard limits can kill expensive agent work or surprise users. This bead is research/design first; implementation should follow only if the design is clearly safe and reversible.\n\n## Success criteria\n- Documents whether systemd slices are appropriate for ACFS agent workflows.\n- Provides proposed resource classes and defaults if useful.\n- Defines tests or manual verification needed before any implementation.","status":"closed","priority":2,"issue_type":"task","created_at":"2026-05-08T04:37:41.210895085Z","created_by":"ubuntu","updated_at":"2026-05-08T09:19:07.265929220Z","closed_at":"2026-05-08T09:19:07.265593692Z","close_reason":"Documented opt-in systemd resource isolation design and verification plan","source_repo":".","compaction_level":0,"original_size":0,"labels":["idea-wizard","performance","safety","swarm"],"dependencies":[{"issue_id":"bd-8qd3d","depends_on_id":"bd-e63fl","type":"blocks","created_at":"2026-05-08T04:41:20.780497665Z","created_by":"ubuntu","metadata":"{}","thread_id":""}]}
-{"id":"bd-8woeg","title":"Design offline artifact pack manifest and trust policy","description":"## What\nDesign the artifact pack format, manifest schema, trust model, and compatibility rules.\n\n## Why\nOffline mode becomes dangerous if ACFS cannot prove exactly what is inside the pack. The pack manifest must be as explicit as `checksums.yaml` and must preserve installer security guarantees.\n\n## Approach\n- Define files, directory layout, pack manifest fields, hashes, source URLs, versions, architectures, and generation timestamp.\n- Specify which modules can be bundled and which still require live auth or provider interaction.\n- Define stale-pack and unsupported-architecture errors.\n- Document how pack verification relates to `checksums.yaml` and verified installers.\n\n## Success Criteria\nImplementation beads can build and consume packs without inventing policy details.\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.","status":"open","priority":1,"issue_type":"task","created_at":"2026-05-08T19:48:55.798865372Z","created_by":"ubuntu","updated_at":"2026-05-08T20:07:40.539448623Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["installer","manifest","offline","security"]}
+{"id":"bd-8woeg","title":"Design offline artifact pack manifest and trust policy","description":"## What\nDesign the artifact pack format, manifest schema, trust model, and compatibility rules.\n\n## Why\nOffline mode becomes dangerous if ACFS cannot prove exactly what is inside the pack. The pack manifest must be as explicit as `checksums.yaml` and must preserve installer security guarantees.\n\n## Approach\n- Define files, directory layout, pack manifest fields, hashes, source URLs, versions, architectures, and generation timestamp.\n- Specify which modules can be bundled and which still require live auth or provider interaction.\n- Define stale-pack and unsupported-architecture errors.\n- Document how pack verification relates to `checksums.yaml` and verified installers.\n\n## Success Criteria\nImplementation beads can build and consume packs without inventing policy details.\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.","status":"closed","priority":1,"issue_type":"task","created_at":"2026-05-08T19:48:55.798865372Z","created_by":"ubuntu","updated_at":"2026-05-08T21:40:41.397008091Z","closed_at":"2026-05-08T21:40:41.396736372Z","close_reason":"Completed offline artifact pack manifest and trust policy.","source_repo":".","compaction_level":0,"original_size":0,"labels":["installer","manifest","offline","security"]}
 {"id":"bd-8wpc","title":"Add 'Learning Hub' to footer links","description":"Add Learning Hub link to the footer section alongside GitHub, NTM, Agent Mail links.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-25T05:16:33.679471Z","updated_at":"2025-12-25T05:24:53.341681Z","closed_at":"2025-12-25T05:24:53.341681Z","close_reason":"Completed as part of parent task agentic_coding_flywheel_setup-umil","source_repo":".","compaction_level":0,"original_size":0,"dependencies":[{"issue_id":"bd-8wpc","depends_on_id":"bd-umil","type":"blocks","created_at":"2025-12-25T05:17:34.226998Z","created_by":"jemanuel","metadata":"{}","thread_id":""}]}
 {"id":"bd-8xx","title":"End-to-end test: acfs-update","description":"## What\nComprehensive testing of acfs-update:\n1. Test on fresh ACFS install (all tools present)\n2. Test on partial install (some tools missing)\n3. Test each category individually\n4. Test --dry-run mode\n5. Test --yes mode (non-interactive)\n6. Test failure handling (simulate failures)\n7. Test logging output\n\n## Test Scenarios\n- Fresh VPS with full ACFS install\n- Existing VPS with previous ACFS version\n- Missing tools (should skip gracefully)\n- Network failures (should report and continue)\n- Permission issues (should report and continue)\n\n## Considerations\n- Need a test VPS or Docker container\n- Some tests may need mocking (network failures)\n- Should test as both root and non-root user\n\n## Success Criteria\n- [ ] All categories update correctly\n- [ ] Dry-run shows accurate preview\n- [ ] Failures handled gracefully\n- [ ] Logs are comprehensive and useful\n- [ ] No regressions in existing functionality","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-21T18:27:10.046030Z","updated_at":"2025-12-21T20:38:12.190216Z","closed_at":"2025-12-21T20:38:12.190216Z","close_reason":"Created comprehensive Docker-based E2E test (tests/vm/test_acfs_update.sh) covering: --help, --dry-run, --quiet, --yes modes; category filters (--agents-only, --shell-only, --no-apt); log file creation; exit codes; missing tool handling; version display. Test follows same pattern as test_install_ubuntu.sh. Shellcheck clean.","source_repo":".","compaction_level":0,"original_size":0,"dependencies":[{"issue_id":"bd-8xx","depends_on_id":"bd-csv","type":"blocks","created_at":"2025-12-21T18:27:35.230950Z","created_by":"daemon","metadata":"{}","thread_id":""}]}
 {"id":"bd-8z5","title":"Create report_skipped_tools() post-install summary","description":"# Task: Create report_skipped_tools() post-install summary\n\n## Context\nPart of EPIC: Checkpoint-Based Checksum Recovery (agentic_coding_flywheel_setup-tx7)\n\n## What to Do\nAfter installation completes, report any tools that were skipped:\n\n### Output\n```\n⚠ The following tools were skipped due to checksum mismatches:\n    → ntm: https://raw.githubusercontent.com/.../install.sh\n    → bv: https://raw.githubusercontent.com/.../install.sh\n\nYou can install these manually after verifying they are safe.\nOr wait for ACFS to update checksums and run: acfs update --stack\n```\n\n### Storage\n- SKIPPED_TOOLS array populated during install\n- Also saved to state.json for persistence\n\n## Acceptance Criteria\n- Only shown if SKIPPED_TOOLS is non-empty\n- Shows tool name and installer URL\n- Provides manual install command\n- Mentions acfs update as alternative\n\n## Files to Modify\n- install.sh: Add report at end of successful install","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-21T17:44:38.550459Z","updated_at":"2025-12-21T19:48:42.459331Z","closed_at":"2025-12-21T19:48:42.459331Z","close_reason":"Added comprehensive skipped tools reporting: record_skipped_tool() with reason and URL, report_skipped_tools() showing detailed summary with manual install commands and acfs update alternative, get_skipped_tools_json() for state persistence.","source_repo":".","compaction_level":0,"original_size":0,"dependencies":[{"issue_id":"bd-8z5","depends_on_id":"bd-4jr","type":"blocks","created_at":"2025-12-21T17:47:33.367598Z","created_by":"daemon","metadata":"{}","thread_id":""}]}