@aperant/framework 0.6.2

package/skills/apt-setup/SKILL.md

@@ -0,0 +1,1075 @@
+---
+name: apt:setup
+description: "Configure Aperant preferences — verification, pipeline, docs policy, parallelization"
+apt-skill-version: {{APT_VERSION}}
+stage: setup
+intent: configure
+when_to_use: "The user wants to change framework preferences — verification style, cross-verification, pipeline behavior, docs policy, or parallelization settings."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:setup [--batch <n> | --reset]"
+gates: []
+---
+<objective>
+Interactive configuration of the Aperant Framework. Presents human-friendly questions
+with sensible defaults so the user never needs to remember flag names.
+
+Settings are saved to `.aperant/config.json` in the project root. Commands like
+/apt:verify-proof, /apt:run, and /apt:plan read this config automatically —
+no flags needed.
+
+For runtime install selection (which CLIs/IDEs to install skills into) the framework
+ships a separate prompt as part of `apt-tools init`. Run with no flags in a TTY and
+you'll see a menu listing all 14 supported runtimes (Claude / Codex / Cursor / Gemini /
+OpenCode / Kilo / Copilot / Antigravity / Windsurf / Augment / Trae / Qwen / Cline /
+CodeBuddy) with auto-detected suggestions marked with `*` (those whose runtime root
+or marker file already exists in the project). Press ENTER to install the suggested
+set, type `all` to install everywhere, or comma-separate specific ids.
+</objective>
+
+<process>
+
+## 0. Detect Prompt Mode
+
+Before running any questions, detect whether the host supports structured prompts:
+
+```bash
+node packages/framework/bin/apt-tools.mjs host-detect
+```
+
+Read `host.capabilities.structured_prompts` from the result.
+
+- **If `true`** (Claude Code, Gemini CLI, OpenCode): use the host's native structured question tool for every `AskUserQuestion([...])` block below:
+  - Claude Code → `AskUserQuestion` tool
+  - Gemini CLI → `ask_user` tool (same shape: `questions[]` with `header`, `question`, `multiSelect`, options)
+  - OpenCode → `question` tool
+- **If `false`** (Codex CLI, Pi, unknown): no native dialog. Fall back to numbered text prompts — print each question with its options as a numbered list and ask the user to reply with the number(s). Example:
+  ```
+  [1/3] Verify Mode — How should verification work?
+    1. Screenshots + Report (Recommended)
+    2. Scores Only
+    3. Full Evidence
+  Reply with a number:
+  ```
+  Read the reply, map it back to the option key, and continue.
+
+Treat every `AskUserQuestion([...])` block in the rest of this skill as an abstract "ask" — the actual tool call depends on the prompt mode you detected here.
+
+## 1. Load Existing Config
+
+```bash
+mkdir -p .aperant
+```
+
+If `.aperant/config.json` exists, read it. Otherwise start from the template defaults:
+
+```json
+{
+  "verification": {
+    "open_report": true,
+    "report_formats": ["html", "md"],
+    "evidence_capture": true,
+    "max_iterations": 3,
+    "strict": false
+  },
+  "multi_model": {
+    "cross_verification": {
+      "enabled": false,
+      "tools": []
+    },
+    "video_review": {
+      "enabled": false,
+      "model": "default",
+      "api_key_env": "GEMINI_API_KEY"
+    }
+  },
+  "pipeline": {
+    "skip_review": false,
+    "auto_branch": true,
+    "branch_prefix": "apt"
+  },
+  "parallelization": {
+    "enabled": false,
+    "max_agents": 3,
+    "use_worktrees": true
+  },
+  "orchestration": {
+    "phase_delegation": "auto",
+    "review_mode": "auto",
+    "debate_mode": "auto"
+  },
+  "tdd": {
+    "iron_law": false
+  }
+}
+```
+
+If `--reset` flag is passed, ignore existing config and start from defaults.
+
+Also check for global defaults at `~/.aperant/defaults.json` — if they exist and no project config exists, use globals as the starting point.
+
+## 1b. Review Mode (existing config detected)
+
+If `.aperant/config.json` already exists AND `--reset` was NOT passed, enter **review mode** instead of running all batches from scratch.
+
+First, run host detection to show resolved orchestration:
+
+```bash
+node packages/framework/bin/apt-tools.mjs reconcile .
+```
+
+Display the current settings summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ APT ► CURRENT SETTINGS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Setting              | Value                        |
+|----------------------|------------------------------|
+| Verification         | {current value}              |
+| Cross-Verification   | {current value}              |
+| Video Review         | {current value}              |
+| Open Report          | {current value}              |
+| Strictness           | {current value}              |
+| Auto Branch          | {current value}              |
+| Code Review          | {current value}              |
+| TDD Iron Law         | {current value}              |
+| Date Format          | {current value}              |
+| Time Format          | {current value}              |
+| Task Index           | {current value}              |
+| Phase Delegation     | {config value} → {resolved}  |
+| Review Mode          | {config value} → {resolved}  |
+| Debate Mode          | {config value} → {resolved}  |
+| Visibility           | {solo / team / oss}          |
+| Host Detected        | {cli name}                   |
+| Agent Teams          | {enabled/disabled}           |
+
+Config: .aperant/config.json
+```
+
+For orchestration rows, show both the config preference and what it resolves to on this host (from reconcile output). Example: `auto → sub-agents` or `agent-team → agent-team`.
+
+Then ask:
+
+```
+AskUserQuestion([
+  {
+    question: "What would you like to change?",
+    header: "Settings",
+    multiSelect: false,
+    options: [
+      { label: "Verification", description: "Verify mode, cross-verification, video review, strictness" },
+      { label: "Pipeline", description: "Auto branch, code review, TDD Iron Law, date/time format, task index" },
+      { label: "Orchestration", description: "Phase delegation, review mode, debate mode, agent teams" },
+      { label: "Team Collaboration", description: "Enable/disable team mode — shared task board, roadmap, members" },
+      { label: "Visibility", description: "Artifact-sharing policy — what leaves your machine (roadmap, team.json, decisions, digests, tasks)" },
+      { label: "Everything", description: "Re-run full setup from scratch" },
+      { label: "Done", description: "Keep current settings" }
+    ]
+  }
+])
+```
+
+**Routing:**
+- "Verification" → jump to **Step 2** (Batch 1 + Batch 2 only), then skip to **Step 4** (mapping) and **Step 5** (write)
+- "Pipeline" → jump to **Step 3b** (Batch 3 only), then skip to **Step 4** and **Step 5**
+- "Orchestration" → jump to **Step 3c** (Batch 4 only), then skip to **Step 4** and **Step 5**
+- "Team Collaboration" → jump to **Step 3d** (Batch 5 only), then skip to **Step 4** and **Step 5**
+- "Visibility" → jump to **Step 3e** (Batch 6 only), then skip to **Step 4** and **Step 5**
+- "Everything" → proceed to **Step 2** and run all batches (same as fresh setup)
+- "Done" → display "Settings unchanged." and exit
+
+For selective edits, **pre-fill the existing values** as the default selection in each question. The user can confirm or change. Unchanged values are preserved — do not overwrite the entire config, only merge the changed section.
+
+After any selective edit, show the confirmation table from **Step 8** with only the changed values highlighted, then exit.
+
+---
+
+## 2. Present Settings (Batch 1: Verification)
+
+```
+AskUserQuestion([
+  {
+    question: "How should verification work when you run /apt:verify-proof?",
+    header: "Verify Mode",
+    multiSelect: false,
+    options: [
+      { label: "Screenshots + Report (Recommended)", description: "Capture screenshots via MCP, terminal output, generate HTML proof report and open it in browser" },
+      { label: "Scores Only", description: "Run tests/typecheck/lint, score 4 dimensions, write qa_signoff.json — no visual evidence" },
+      { label: "Full Evidence", description: "Screenshots + terminal output + video review + report in all formats (html, md, archive)" }
+    ]
+  },
+  {
+    question: "Enable cross-verification? Other AI CLIs independently verify your implementation alongside Claude Code.",
+    header: "Cross-Verification",
+    multiSelect: false,
+    options: [
+      { label: "Claude Code only (Recommended)", description: "Fastest — Claude Code handles all verification. No extra tools needed." },
+      { label: "Choose verification tools", description: "Select which AI CLIs to use for independent cross-verification (text + screenshot based, no API keys needed)." }
+    ]
+  }
+])
+```
+
+### If "Choose verification tools" selected:
+
+```
+AskUserQuestion([
+  {
+    question: "Which AI CLIs should cross-verify? (Claude Code is always included as the primary verifier)",
+    header: "Verification Tools",
+    multiSelect: true,
+    options: [
+      { label: "Gemini CLI", description: "Google's gemini command — text + screenshot verification. Free, no API key needed for CLI." },
+      { label: "Codex CLI", description: "OpenAI's codex command — text-based code verification." },
+      { label: "Open Code", description: "opencode command — open-source AI coding CLI." }
+    ]
+  }
+])
+```
+
+### Video review question (separate from cross-verification):
+
+```
+AskUserQuestion([
+  {
+    question: "Enable Gemini video review for UI verification? (Uses Gemini API, not the CLI — requires GEMINI_API_KEY)",
+    header: "Video Review",
+    multiSelect: false,
+    options: [
+      { label: "No (Recommended)", description: "Skip video analysis — screenshots + text verification are usually sufficient" },
+      { label: "Yes", description: "Record screen interactions and send video to Gemini API for visual analysis. Catches hover states, animations, transitions." }
+    ]
+  }
+])
+```
+
+### If video review enabled:
+
+```
+AskUserQuestion([
+  {
+    question: "Which Gemini model for video analysis?",
+    header: "Gemini Model",
+    multiSelect: false,
+    options: [
+      { label: "Balanced (Recommended)", description: "gemini-2.5-flash — best detail-to-speed ratio, reads exact text and star counts" },
+      { label: "Thorough", description: "gemini-3.1-pro-preview — catches hover states and dropdown bugs, ~26s per video" },
+      { label: "Fast", description: "gemini-3.1-flash-lite-preview — ~6s per video, good for CI pass/fail" }
+    ]
+  }
+])
+```
+
+### Remaining verification settings:
+
+```
+AskUserQuestion([
+  {
+    question: "Open the proof report in browser automatically after verification?",
+    header: "Auto-Open",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Opens report.html in your default browser when verification completes" },
+      { label: "No", description: "Just write the files — you open them manually" }
+    ]
+  }
+])
+```
+
+## 3. Present Settings (Batch 2: Pipeline)
+
+```
+AskUserQuestion([
+  {
+    question: "How strict should verification be?",
+    header: "Strictness",
+    multiSelect: false,
+    options: [
+      { label: "Fix and retry (Recommended)", description: "If issues found, attempt to fix them and re-verify (up to 3 iterations)" },
+      { label: "Strict — fail immediately", description: "Report issues but don't attempt fixes. Good for CI or audit mode." }
+    ]
+  },
+  {
+    question: "Create feature branches automatically when running /apt:run?",
+    header: "Branching",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Creates apt/{task-name} branch for each pipeline run" },
+      { label: "No", description: "Commit directly to current branch" }
+    ]
+  },
+  {
+    question: "Include code review as the final pipeline step?",
+    header: "Auto Review",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Multi-pass code review after verification — catches logic, security, quality, architecture issues" },
+      { label: "No", description: "Skip review step in /apt:run — just plan, execute, verify" }
+    ]
+  },
+  {
+    question: "Enforce TDD Iron Law? (Every subtask must land a failing test commit before the implementation commit.)",
+    header: "TDD Iron Law",
+    multiSelect: false,
+    options: [
+      { label: "No (Recommended)", description: "Leave TDD as a soft convention. Executors choose when to write tests first." },
+      { label: "Yes", description: "Opt in to structural red-green-refactor enforcement. Audit gate runs during /apt:verify." }
+    ]
+  },
+  {
+    question: "After /apt:ship creates a PR, auto-suggest running /apt:pr-review for deep multi-agent review?",
+    header: "PR Review Auto-Suggest",
+    multiSelect: false,
+    options: [
+      { label: "Always (Recommended)", description: "One-line tip after shipping. Noop on npm-publish-only flows." },
+      { label: "Ask me", description: "Prompt [Y/n] each time — choose per-PR." },
+      { label: "Never", description: "Silent. Run /apt:pr-review manually if needed." }
+    ]
+  }
+])
+```
+
+### Task-level worktree isolation (only if host supports worktrees)
+
+First check `host.capabilities.worktrees` from the host-detect output. If `false` (Codex, Gemini, OpenCode), skip this question and leave `task_isolation.worktree_per_task` at its default (`false`).
+
+If `true` (Claude Code), ask:
+
+```
+AskUserQuestion([
+  {
+    question: "Create an isolated git worktree + branch for each new task? Recommended when running multiple agents in parallel on the same repo.",
+    header: "Task Worktree",
+    multiSelect: false,
+    options: [
+      { label: "No (Recommended for solo work)", description: "Edit in-place on the current branch. Fine when you're the only agent touching this repo." },
+      { label: "Yes", description: "Every new task forks its own branch and worktree under .aperant/worktrees/{scope}/{task-id}/. Multiple /apt runs can execute in parallel without stepping on each other." }
+    ]
+  }
+])
+```
+
+Map the answer:
+- "Yes" → `task_isolation.worktree_per_task: true`
+- "No" → `task_isolation.worktree_per_task: false`
+
+Other `task_isolation` keys (`branch_prefix`, `from_branch`, `push_on_create`, `cleanup_on_close`) keep their template defaults unless the user edits the config file directly.
+
+## 3b. Present Settings (Batch 3: Preferences)
+
+```
+AskUserQuestion([
+  {
+    question: "How should dates be displayed in task folders and reports?",
+    header: "Date Format",
+    multiSelect: false,
+    options: [
+      { label: "DD-MM-YY (e.g. 13-04-26)", description: "Day first — common in Europe, UK, and most of the world" },
+      { label: "MM-DD-YY (e.g. 04-13-26)", description: "Month first — common in the US" },
+      { label: "YY-MM-DD (e.g. 26-04-13) (Recommended)", description: "Year first — ISO-style, sorts chronologically in file explorers" }
+    ]
+  },
+  {
+    question: "How should times be displayed?",
+    header: "Time Format",
+    multiSelect: false,
+    options: [
+      { label: "24-hour (e.g. 14:30) (Recommended)", description: "No AM/PM — common in most of the world" },
+      { label: "12-hour (e.g. 2:30 PM)", description: "With AM/PM — common in the US" }
+    ]
+  },
+  {
+    question: "Auto-generate a task index file? (lightweight project management view)",
+    header: "Task Index",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Generates .aperant/tasks/INDEX.md with date, status, and title for every task — updated automatically" },
+      { label: "No", description: "Skip index generation" }
+    ]
+  }
+])
+```
+
+## 3b-design. Present Settings (Batch 3b: Design Taste) (C26)
+
+Optional step. Offers the user a starting aesthetic for the `apt:design`
+pipeline. When picked, copies a reference taste profile from
+`packages/framework/templates/design-taste/<direction>.yaml` into
+`.aperant/design/taste.yaml`. `apt:design` reads that file on every run
+and injects it as a TASTE_BLOCK so generated UI reflects project
+identity instead of defaulting to generic-SaaS-Tailwind.
+
+If `.aperant/design/taste.yaml` already exists, confirm overwrite before
+copying. Default is "Skip" so this step is zero-friction for users who
+don't care about aesthetics yet.
+
+```
+AskUserQuestion([
+  {
+    question: "Pick a starting design taste for apt:design, or skip. You can edit or re-pick later by copying a file from packages/framework/templates/design-taste/ into .aperant/design/taste.yaml.",
+    header: "Design Taste",
+    multiSelect: false,
+    options: [
+      { label: "Skip (Recommended for now)", description: "No taste declared. apt:design falls back to generic-SaaS-Tailwind with a note pointing here." },
+      { label: "Brutalist", description: "Raw, utilitarian, unafraid of ugly. Dense info, loud contrast, square corners. Think Craigslist, early Basecamp, Are.na." },
+      { label: "Editorial", description: "Magazine-like, reading-first, generous rhythm. Serif body type, warm neutrals, slow motion. Think long-form readers, docs sites." },
+      { label: "Enterprise-Clean", description: "Trustworthy, quiet, dense-when-it-counts. B2B dashboards, admin consoles. Think Stripe Dashboard, Linear enterprise." },
+      { label: "Playful", description: "Saturated, bouncy, high-personality. Consumer + creative tools. Rounded geometry, spring motion. Think Duolingo, Arc Browser." }
+    ]
+  }
+])
+```
+
+### Map answer → copy template
+
+- "Skip" → no-op. Leave `.aperant/design/taste.yaml` untouched.
+- "Brutalist" → copy `packages/framework/templates/design-taste/brutalist.yaml`
+- "Editorial" → copy `packages/framework/templates/design-taste/editorial.yaml`
+- "Enterprise-Clean" → copy `packages/framework/templates/design-taste/enterprise-clean.yaml`
+- "Playful" → copy `packages/framework/templates/design-taste/playful.yaml`
+
+For any non-Skip choice:
+
+```bash
+mkdir -p .aperant/design
+```
+
+If `.aperant/design/taste.yaml` already exists, ask:
+
+```
+AskUserQuestion([
+  {
+    question: "`.aperant/design/taste.yaml` already exists. Overwrite with the {direction} starter profile?",
+    header: "Overwrite?",
+    multiSelect: false,
+    options: [
+      { label: "No (keep existing)", description: "Leave your current taste.yaml untouched." },
+      { label: "Yes, overwrite", description: "Replace with the selected starter profile. You can re-edit it afterwards." }
+    ]
+  }
+])
+```
+
+If "Yes, overwrite" or the file does not yet exist:
+
+```bash
+cp packages/framework/templates/design-taste/<direction>.yaml .aperant/design/taste.yaml
+```
+
+Then tell the user:
+```
+Design taste set to <direction>.
+Edit .aperant/design/taste.yaml anytime — palette, type, motion, density,
+and anti_patterns are all free-form YAML. apt:design reads this file on
+every run.
+
+See packages/framework/docs/design-taste.md for field-by-field guidance.
+```
+
+After this batch, add a row to the Step 8 confirmation table:
+
+```
+| Design Taste         | {Skip / Brutalist / Editorial / Enterprise-Clean / Playful} |
+```
+
+---
+
+## 3c. Present Settings (Batch 4: Orchestration)
+
+First, detect the host environment:
+
+```bash
+node packages/framework/bin/apt-tools.mjs host-detect
+```
+
+**If the host is `claude-code` and `capabilities.agent_teams` is `false`:**
+
+Agent teams unlock the best orchestration modes (cross-examining reviewers, natural debates). Offer to enable them:
+
+```
+AskUserQuestion([
+  {
+    question: "Agent teams are not enabled for this project. Enable them? (Recommended — unlocks best review and debate modes)",
+    header: "Agent Teams",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Enables agent teams for this project. Reviewers can cross-examine findings, debaters communicate directly." },
+      { label: "No", description: "Use sub-agents only. Still parallel, but no inter-agent communication." }
+    ]
+  }
+])
+```
+
+If "Yes": write the env var to `.claude/settings.local.json` (gitignored — per-developer, not forced on collaborators):
+
+```bash
+# Read existing settings.local.json or start fresh
+if [ -f .claude/settings.local.json ]; then
+  # Merge env into existing file
+fi
+```
+
+Write/merge into `.claude/settings.local.json`:
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+If the file already exists with other settings, merge the `env` key — do not overwrite existing settings. Use Read + JSON merge + Write.
+
+After writing, note to the user: `"Agent teams enabled. Takes effect on next Claude Code session in this project."`
+
+**If the host is not `claude-code`, or agent teams are already enabled:** skip this question and proceed directly to orchestration mode selection.
+
+---
+
+```
+AskUserQuestion([
+  {
+    question: "How should multi-agent workflows be orchestrated?",
+    header: "Orchestration",
+    multiSelect: false,
+    options: [
+      { label: "Auto (Recommended)", description: "Automatically picks the best strategy based on which AI CLI you're using. Works everywhere." },
+      { label: "Choose manually", description: "Set explicit preferences for phase delegation, code review, and debates." }
+    ]
+  }
+])
+```
+
+If "Choose manually":
+
+```
+AskUserQuestion([
+  {
+    question: "How should pipeline phases be delegated?",
+    header: "Phase Delegation",
+    multiSelect: false,
+    options: [
+      { label: "Auto", description: "Best available for your CLI" },
+      { label: "Agent Team", description: "Uses Claude Code agent teams (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)" },
+      { label: "Sub-Agents", description: "Spawns separate sub-agents for each phase (available on Claude Code and Codex)" },
+      { label: "Sequential", description: "Runs everything inline — works on any CLI" }
+    ]
+  },
+  {
+    question: "How should multi-reviewer code reviews run?",
+    header: "Review Mode",
+    multiSelect: false,
+    options: [
+      { label: "Auto", description: "Best available for your CLI" },
+      { label: "Agent Team", description: "Uses Claude Code agent teams (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)" },
+      { label: "Sub-Agents", description: "Spawns 6 parallel sub-agents for review (available on Claude Code and Codex)" },
+      { label: "Sequential", description: "Runs 6 review passes inline, one at a time — works on any CLI" }
+    ]
+  },
+  {
+    question: "How should roundtable debates run?",
+    header: "Debate Mode",
+    multiSelect: false,
+    options: [
+      { label: "Auto", description: "Best available for your CLI" },
+      { label: "Agent Team", description: "Uses Claude Code agent teams (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)" },
+      { label: "Sub-Agents", description: "Spawns 10 parallel debater agents (available on Claude Code and Codex)" },
+      { label: "Sequential", description: "Runs 10 perspectives inline, one at a time — works on any CLI" }
+    ]
+  }
+])
+```
+
+## 3d. Present Settings (Batch 5: Team Collaboration)
+
+Ask whether the user wants team collaboration features:
+
+```
+AskUserQuestion([
+  {
+    question: "Are you working on this repo with other people (co-founders, contributors, an open-source community)?",
+    header: "Team Mode",
+    multiSelect: false,
+    options: [
+      { label: "Yes — enable team collaboration", description: "Shares task board, roadmap, and who's working on what via git. Gitignored personal state stays local." },
+      { label: "No — solo project", description: "Skip team features. All framework state stays local." }
+    ]
+  }
+])
+```
+
+### If "Yes — enable team collaboration" selected:
+
+Give the user a brief overview before running setup:
+
+```
+Team Mode enables shared files so collaborators can see each other's work:
+
+  .aperant/team.json         — members (auto-detected from git config)
+  .aperant/team-status/      — per-agent "who's working on what" (gitignored,
+                               ephemeral, TTL-expired; the canonical cross-
+                               agent signal)
+  .aperant/tasks/INDEX.md    — task history (date, status, owner)
+  .aperant/roadmap/          — milestones, phases, ownership
+
+These files are committed to git. Personal state (state.json, locks,
+events, team-status/, proof, paused sessions) stays gitignored.
+
+Updates happen automatically when you use /apt commands — no manual
+syncing required. Your git identity (name + email) identifies you
+to other collaborators.
+```
+
+Then initialize team mode:
+
+```bash
+node packages/framework/bin/apt-tools.mjs team init .
+```
+
+This:
+- Creates `.aperant/team.json` with `enabled: true`
+- Auto-registers the current user via `git config user.name` / `user.email`
+- Per-agent coordination is written to `.aperant/team-status/{agent-id}.json`
+  automatically on lifecycle transitions (gitignored, ephemeral)
+- From now on, every task create/update/close auto-updates the shared board
+  (events also append to `.aperant/events/{YYYY-MM-DD}.jsonl`)
+
+**If the user has no git identity configured**, the `team init` call will still succeed but won't register a member. Warn them:
+```
+Git identity not found. Run these before using team features:
+  git config user.name "Your Name"
+  git config user.email "you@example.com"
+
+Your identity will be auto-registered on your next /apt command.
+```
+
+### Roadmap initialization (optional)
+
+After team init, offer to bootstrap a roadmap:
+
+```
+AskUserQuestion([
+  {
+    question: "Initialize a project roadmap? (You can add milestones and phases later)",
+    header: "Roadmap",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "Creates .aperant/roadmap/ with an empty milestones.json and ROADMAP.md" },
+      { label: "Skip", description: "You can run `apt-tools roadmap init` later" }
+    ]
+  }
+])
+```
+
+If "Yes":
+```bash
+node packages/framework/bin/apt-tools.mjs roadmap init .
+```
+
+Then tell the user:
+```
+Roadmap initialized at .aperant/roadmap/project/ROADMAP.md
+
+To add milestones and phases, use:
+  apt-tools roadmap add-milestone . --id m1 --title "MVP" --goal "Ship paid version"
+  apt-tools roadmap add-phase . --milestone m1 --id p1 --title "Setup" --owner "Andre"
+  apt-tools roadmap set-phase-status . --milestone m1 --phase p1 --status in-progress
+```
+
+### If "No — solo project" selected:
+
+Skip team setup. Proceed directly to **Step 4**.
+
+If team mode is being *disabled* (user previously had it enabled):
+```bash
+node packages/framework/bin/apt-tools.mjs team disable .
+```
+
+---
+
+## 3e. Present Settings (Batch 6: Visibility policy)
+
+The visibility policy (C35) controls what leaves the user's machine: which
+`.aperant/` files get committed to git. Default is `solo` — nothing trackable
+except the durable framework scaffolding (config.json, templates, prompts,
+etc.). Users opt into sharing deliberately via this step.
+
+### 3e.1 Collect signals first
+
+Before asking any questions, gather deterministic signals so questions can
+be skipped when the answer is already on disk:
+
+```bash
+node packages/framework/bin/apt-tools.mjs audit visibility-signals .
+```
+
+This returns JSON with:
+- `publicRemote.{isPublic, url, host}` — true only for github.com / gitlab.com / bitbucket.org
+- `existingGitignore.{exists, hasAperantEntries, allowsAny, bypassedByShare}` — list of `!` rules currently in `.aperant/.gitignore` and which of them the current policy does NOT authorize (indicates a hand-edited gitignore drifting from config)
+- `teamEnabled` — `team.json.enabled === true`
+- `digestsEnabled` — `config.digests.enabled === true`
+- `currentPolicy.{visibility, share}` — what's in config right now
+
+### 3e.2 Pick 1–3 questions based on signals
+
+Choose at most 3 questions from the candidate list below. Skip any question
+the signals already answer. **Always include the preset pick as the final
+question.**
+
+Candidate questions:
+
+1. **(always asked, final)** Pick a visibility preset:
+   - **Solo** — nothing shared. Safe default for solo work or private repos.
+   - **Team** — roadmap + team.json + decisions + digests shared; per-task specs stay local.
+   - **OSS Public** — same toggles as Team, but the framework will emit loud warnings when origin is a public host.
+
+   If `publicRemote.isPublic === true`, append a consequence line to the preset pick: "This repo has a public remote ({host}). Files you opt in to will be world-readable."
+
+2. **(conditional: publicRemote.isPublic && currentPolicy.visibility !== 'solo')** "This repo has a public remote ({host}). Committing `.aperant/` files will make them world-readable. Proceed?"
+
+3. **(conditional: teamEnabled === true && currentPolicy.share.team.roster !== true)** "Team mode is on but `.aperant/team.json` is gitignored. Share the roster so collaborators see each other?"
+
+4. **(conditional: existingGitignore.hasAperantEntries && currentPolicy.visibility === 'solo')** "Your current `.gitignore` already shares some `.aperant/` files. Keep that layout (Team preset) or tighten to Solo?"
+
+5. **(conditional: share.tasks not covered by preset already)** "Share per-task specs and plans? Useful for review + async collaboration; adds noise to git history. Default No."
+
+6. **(conditional: digestsEnabled && currentPolicy.share.digests === null)** "Digests are on for this project. Share the narrative digests (weekly summaries) with the team? Inherited default: Yes."
+
+### 3e.3 Apply + audit
+
+After the preset + toggle overrides are resolved:
+
+1. Write the merged `share` block into `.aperant/config.json` via the existing config-writer path (caller id `setup`). Do NOT remove unrelated keys — only merge the `share` block.
+2. Rewrite `.aperant/.gitignore` via:
+   ```bash
+   node packages/framework/bin/apt-tools.mjs config upgrade-gitignore .
+   ```
+   The upgrade helper reads the updated config automatically.
+3. Run the privacy audit:
+   ```bash
+   node packages/framework/bin/apt-tools.mjs audit privacy .
+   ```
+4. Display the audit result inline:
+   - If `status === "ok"` (no violations): "Your working tree already matches the new policy."
+   - If `status === "violations-found"`: print the violation list + the suggested `untrackCommand`, and tell the user to run it themselves. **Do not auto-run.**
+5. Only if the user explicitly asks about purging history, mention `audit privacy . --scrub` — it prints `git filter-repo` commands + a 6-step checklist and never executes them.
+
+### 3e.4 Confirmation row
+
+Add a row to the Step 8 table:
+```
+| Visibility | {solo/team/oss} (overrides: share.tasks=true, …) |
+```
+
+If no custom overrides, drop the parenthetical.
+
+---
+
+## 3f. Present Settings (Batch 7: Docs Policy)
+
+The **docs-coherence policy** (C33) controls what the framework does when a
+task's diff touches a documented surface. There are three policy kinds:
+
+| Kind | Meaning | Used for (default) |
+|------|---------|--------------------|
+| `auto-update` | Reviewer + executor patch the surface inline | INTERNAL files (REGISTRY.md, milestones.json, project_index.json, .aperant/tasks/**) |
+| `flag-drift` | Reviewer emits a finding; no auto-edit | EXTERNAL prose (CLAUDE.md, AGENTS.md, READMEs, docs/**) |
+| `skip` | Don't audit this surface at all | opt-out |
+
+The defaults match `packages/framework/templates/docs-policy-defaults.json`:
+internal state under `auto-update`, external prose under `flag-drift`.
+Written to `.aperant/config.json.docs_policy` as a flat
+`{ "<glob-or-path>": "auto-update" | "flag-drift" | "skip" }` map.
+
+### 3f.1 Detect structured-prompt support
+
+Re-use the detection from Step 0 (`structured_prompts` capability). If the
+host supports `AskUserQuestion(multiSelect: true)`, present the policy
+picker as a single multi-select; otherwise use the numbered-input fallback
+template shared with Batch 5.
+
+### 3f.2 Present the picker
+
+```
+AskUserQuestion([
+  {
+    question: "Which documented surfaces should /apt:run audit, and how?",
+    header: "Docs Policy",
+    multiSelect: true,
+    options: [
+      { label: "CLAUDE.md — flag drift (recommended)",
+        description: "External prose; reviewer emits findings, never auto-edits." },
+      { label: "AGENTS.md — flag drift (recommended)",
+        description: "Constitution / conventions. Findings only." },
+      { label: "packages/*/README.md — flag drift (recommended)",
+        description: "Per-package READMEs. Findings only." },
+      { label: "docs/** — flag drift (recommended)",
+        description: "All markdown under docs/. Findings only." },
+      { label: ".aperant/roadmap/**/milestones.json — auto-update (recommended)",
+        description: "Milestone rollup + phase status. Auto-patched." },
+      { label: ".aperant/features/REGISTRY.md — auto-update (recommended)",
+        description: "Registry totals refresh on executor post-step." },
+      { label: ".aperant/features/*.json — auto-update (recommended)",
+        description: "Per-area feature files. Stubs appended on post-step." },
+      { label: ".aperant/project_index.json — auto-update (recommended)",
+        description: "Workspace deps & package metadata." },
+      { label: ".aperant/tasks/** — auto-update (recommended)",
+        description: "Task artifacts stay coherent across commit boundaries." }
+    ]
+  }
+])
+```
+
+For hosts without structured prompts, present the same options as a
+numbered list (Batch 5 style) and read the response as a comma-separated
+set of indices to toggle to `skip`. The user is opting OUT of the default
+audit, not re-selecting every surface.
+
+### 3f.3 Map answers to `.aperant/config.json.docs_policy`
+
+- Every surface the user LEFT at its default gets its default value
+  (auto-update or flag-drift from the recommendations above).
+- Every surface the user opted OUT of → `"skip"`.
+- The merged map replaces any existing `docs_policy` block in
+  `config.json`. Users can hand-edit for finer-grained control; this
+  picker is the onboarding happy path.
+
+### 3f.4 Review-Mode routing entry
+
+Extend the existing "1b. Review Mode" routing table (§1b) to include
+"Docs Policy" as a selectable edit target — jumping directly back into
+this Batch 7 picker.
+
+### 3f.5 Confirmation row
+
+Add a row to the Step 8 table:
+```
+| Docs Policy | {summary — "defaults" when no surfaces opted out, else "defaults + skip: <list>"} |
+```
+
+---
+
+## 4. Map Answers to Config
+
+Map the user's selections to config values:
+
+**Verify Mode:**
+- "Screenshots + Report" → `evidence_capture: true`, `report_formats: ["html", "md"]`
+- "Scores Only" → `evidence_capture: false`, `report_formats: []`
+- "Full Evidence" → `evidence_capture: true`, `report_formats: ["html", "md", "archive"]`
+
+**Cross-Verification:**
+- "Claude Code only" → `multi_model.cross_verification.enabled: false`, `multi_model.cross_verification.tools: []`
+- "Choose verification tools" → `multi_model.cross_verification.enabled: true`, `multi_model.cross_verification.tools: [selected tools]`
+  - Tool identifiers: `"gemini-cli"`, `"codex-cli"`, `"opencode"`
+  - Example: `["gemini-cli", "codex-cli"]`
+
+**Video Review:**
+- "No" → `multi_model.video_review.enabled: false`
+- "Yes" → `multi_model.video_review.enabled: true`
+
+**Gemini Model (video review only):**
+- "Balanced" → `multi_model.video_review.model: "default"`
+- "Thorough" → `multi_model.video_review.model: "thorough"`
+- "Fast" → `multi_model.video_review.model: "fast"`
+
+**Auto-Open:** "Yes" → `open_report: true`, "No" → `open_report: false`
+
+**Strictness:** "Fix and retry" → `strict: false, max_iterations: 3`, "Strict" → `strict: true, max_iterations: 1`
+
+**Branching:** "Yes" → `auto_branch: true`, "No" → `auto_branch: false`
+
+**Auto Review:** "Yes" → `skip_review: false`, "No" → `skip_review: true`
+
+**TDD Iron Law:** "No" → `tdd.iron_law: false`, "Yes" → `tdd.iron_law: true`
+
+**PR Review Auto-Suggest:**
+- "Always (Recommended)" → `pr_review.suggest_after_ship: "always"`
+- "Ask me" → `pr_review.suggest_after_ship: "ask"`
+- "Never" → `pr_review.suggest_after_ship: "never"`
+
+**Date Format:**
+- "DD-MM-YY" → `preferences.date_format: "DD-MM-YY"`
+- "MM-DD-YY" → `preferences.date_format: "MM-DD-YY"`
+- "YY-MM-DD" → `preferences.date_format: "YY-MM-DD"`
+
+**Time Format:**
+- "24-hour" → `preferences.time_format: "24h"`
+- "12-hour" → `preferences.time_format: "12h"`
+
+**Task Index:** "Yes" → `preferences.task_index: true`, "No" → `preferences.task_index: false`
+
+**Orchestration (Auto mode):** "Auto (Recommended)" → all three fields set to `"auto"`:
+- `orchestration.phase_delegation: "auto"`
+- `orchestration.review_mode: "auto"`
+- `orchestration.debate_mode: "auto"`
+
+**Orchestration (Manual mode):** map each question independently:
+- "Auto" → `"auto"`
+- "Agent Team" → `"agent-team"`
+- "Sub-Agents" → `"sub-agents"`
+- "Sequential" → `"sequential"`
+
+## 5. Write Config
+
+Write merged config to `.aperant/config.json`:
+
+```bash
+mkdir -p .aperant
+```
+
+Write the JSON file with 2-space indentation. Bump `version` to 4 if upgrading from an older config (versions 2/3 load forward-compatibly — the new `tdd` block is optional).
+
+## 6. Save as Global Defaults (Optional)
+
+```
+AskUserQuestion([
+  {
+    question: "Save these as default settings for all new projects?",
+    header: "Defaults",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "New projects start with these settings (saved to ~/.aperant/defaults.json)" },
+      { label: "No (Recommended)", description: "Only apply to this project" }
+    ]
+  }
+])
+```
+
+If "Yes":
+```bash
+mkdir -p ~/.aperant
+```
+Write `~/.aperant/defaults.json` with the same config.
+
+## 7. Check Prerequisites
+
+### If cross-verification tools selected:
+
+For each selected tool, check if the CLI is available:
+
+```bash
+which gemini 2>/dev/null && echo "found" || echo "not found"
+which codex 2>/dev/null && echo "found" || echo "not found"
+which opencode 2>/dev/null && echo "found" || echo "not found"
+```
+
+For any tool not found, inform the user:
+```
+Cross-verification tool not found: {tool}
+
+Install it:
+  Gemini CLI:  npm install -g @anthropic-ai/gemini-cli  (or see https://github.com/anthropics/gemini-cli)
+  Codex CLI:   npm install -g @openai/codex              (or see https://github.com/openai/codex)
+  Open Code:   go install github.com/opencode-ai/opencode@latest
+
+Cross-verification will skip unavailable tools at runtime.
+```
+
+### If video review enabled:
+
+```bash
+echo "${GEMINI_API_KEY:-${GOOGLE_API_KEY:-NOT_SET}}"
+```
+
+If not set, inform the user:
+```
+Gemini video review is enabled but no API key found.
+
+Set your key:
+  export GEMINI_API_KEY="your-key"
+
+Get a free key at: https://aistudio.google.com/apikey
+
+Note: This key is ONLY used for video review (sending recorded videos to Gemini API).
+Cross-verification uses the Gemini CLI directly — no API key needed for that.
+```
+
+## 8. Confirm
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ APT ► SETTINGS UPDATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Setting              | Value                        |
+|----------------------|------------------------------|
+| Verification         | {Screenshots/Scores/Full}    |
+| Cross-Verification   | {Off / gemini-cli, codex-cli}|
+| Video Review         | {Off / On (balanced)}        |
+| Open Report          | {Yes/No}                     |
+| Strictness           | {Fix & retry/Strict}         |
+| Auto Branch          | {Yes/No}                     |
+| Code Review          | {Yes/No}                     |
+| TDD Iron Law         | {Yes/No}                     |
+| Date Format          | {DD-MM-YY / MM-DD-YY / YY-MM-DD} |
+| Time Format          | {24h / 12h}                  |
+| Task Index           | {Yes/No}                     |
+| Design Taste         | {Skip / Brutalist / Editorial / Enterprise-Clean / Playful} |
+| Phase Delegation     | {Auto / Agent Team / Sub-Agents / Sequential} |
+| Review Mode          | {Auto / Agent Team / Sub-Agents / Sequential} |
+| Debate Mode          | {Auto / Agent Team / Sub-Agents / Sequential} |
+| Visibility           | {solo / team / oss} (overrides if any)        |
+| Saved as Defaults    | {Yes/No}                     |
+
+Config saved to: .aperant/config.json
+
+Commands now use these settings automatically:
+  /apt:verify       — uses your verification prefs
+  /apt:verify-proof — uses cross-verification + video review prefs
+  /apt:run          — uses your pipeline + branching prefs
+  /apt:setup        — change settings anytime
+```
+
+### 8a. PreCompact Hook Status
+
+After confirming settings, check whether the framework's PreCompact hook is
+installed in `.claude/settings.local.json` (per-developer, gitignored — each
+collaborator opts in by running `apt-tools init` locally). This hook keeps
+`/apt:run`, `/apt:execute`, `/apt:review`, and other long-running commands
+alive across Claude Code's auto-compact — it injects task resume instructions
+into the compacted summary so the post-compact agent continues from
+`build-progress.json` instead of asking the human to restart.
+
+```bash
+# The hook is installed by `apt-tools init` automatically. Check it:
+grep -l 'apt-tools.mjs precompact-hook' .claude/settings.local.json 2>/dev/null && \
+  echo "PreCompact hook: installed" || \
+  echo "PreCompact hook: NOT installed — run apt-tools init to add it"
+```
+
+If missing, re-run `node packages/framework/bin/apt-tools.mjs init .` — it's
+idempotent and only touches the hook entry. Users who want to opt out can
+remove the entry from `.claude/settings.local.json` manually; the framework
+will still work, but long runs will fall back to the `--continue` flow after
+compaction (human re-invocation required).
+
+**Host parity note.** The PreCompact hook is a Claude Code feature. As of this
+writing:
+
+| Host | Auto-compact? | PreCompact-equivalent hook? | Framework behavior |
+|------|---------------|----------------------------|---------------------|
+| Claude Code | Yes | Yes (`PreCompact`) | Full resume-across-compact via this hook |
+| Codex CLI (`codex`) | Yes (internal) | No public hook API | Bailout removal still helps; after compaction the agent re-reads `build-progress.json` + `implementation_plan.json` from instructions in the skill itself |
+| Gemini CLI | Partial (session summary) | No | Same fallback — checkpoint files are the source of truth |
+| OpenCode CLI | Varies by adapter | No | Same fallback |
+
+On non-Claude-Code hosts the framework still works because the apt-execute and
+apt-executor skills explicitly instruct the agent to treat `build-progress.json`
+as the authoritative checkpoint and to re-read it after any context reset. The
+PreCompact hook is an *optimization* for Claude Code — it injects the resume
+block directly into the compacted summary so the agent doesn't have to
+rediscover which task is active. Without it, the agent relies on the standing
+skill instructions plus whatever the host's own summarization preserved.
+
+</process>