multi-forge 0.2.0__py3-none-any.whl

forge/_extensions/skills/qa/resources/checklist/0-enable.md

@@ -0,0 +1,78 @@
+## 0. Install Forge (New User Flow)
+
+This simulates what a new user does to install Forge from scratch.
+
+### 0.1 Pre-requisites Check
+
+<!-- auto -->
+
+```bash
+# Check you have the required tools
+python3 --version   # Need 3.11+
+uv --version        # Need uv package manager
+git --version       # Need git
+```
+
+- [ ] Python 3.11+ installed
+- [ ] uv installed
+- [ ] git installed
+
+### 0.2 Verify Clean State
+
+<!-- auto -->
+
+```bash
+# Ensure no previous Forge installation
+ls -la ~/.forge/           # Should not exist
+which forge                # Should not be on PATH (or points to dev venv)
+
+# Check Claude settings have no Forge hooks
+cat ~/.claude/settings.json | jq '.hooks' 2>/dev/null || true
+cat ~/.claude/settings.local.json | jq '.hooks' 2>/dev/null || true
+```
+
+- [ ] `~/.forge/` does not exist
+- [ ] No Forge hooks in `~/.claude/settings.json`
+- [ ] No Forge hooks in `~/.claude/settings.local.json`
+
+### 0.3 Install via setup.sh
+
+<!-- auto -->
+
+```bash
+# Install Forge using the local copy (already in container at /forge/)
+cd /forge && /forge/scripts/setup.sh --local
+```
+
+- [ ] Prerequisites check passes
+- [ ] Repository linked at `~/.forge/repo/` (symlink to `/forge`)
+- [ ] `setup.sh --local` completes successfully
+- [ ] `forge` binary available (at `~/.local/bin/forge` for `--local` mode)
+- [ ] Success message displayed
+
+> Note: `setup.sh` installs Forge but does not automatically install Claude extensions. After install, run:
+>
+> - `forge extension enable --scope user` (installs commands/agents/skills/hooks)
+
+### 0.4 Verify Installation
+
+<!-- auto -->
+
+```bash
+# Source your profile (or restart terminal)
+source ~/.zshrc  # or ~/.bash_profile
+
+# Verify forge is on PATH
+which forge
+forge --version
+
+# Check installation artifacts
+ls -la ~/.forge/
+ls -la ~/.forge/repo/
+```
+
+- [ ] `forge` command available on PATH
+- [ ] `~/.forge/` directory created
+- [ ] `~/.forge/repo/` contains repo (symlink or clone)
+
+---

forge/_extensions/skills/qa/resources/checklist/1-preflight.md

@@ -0,0 +1,24 @@
+<!-- prereq: 0.3 -->
+
+## 1. Pre-Flight for Extension Tests
+
+### 1.1 Pre-Flight Checks
+
+<!-- auto -->
+
+```bash
+# Navigate to test repo
+cd $FORGE_TEST_REPO
+
+# IMPORTANT: Verify pre-existing user settings exist
+cat .claude/settings.local.json | jq '.'
+# Should include permissions.allow ["Bash(npm test)", "Bash(uv run pytest*)"] and env.MY_CUSTOM_VAR="should-survive-forge".
+
+# Optional: verify project settings file exists too
+ls -la .claude/settings.json 2>/dev/null || true
+```
+
+- [ ] Test repo has `.claude/settings.local.json` with pre-existing settings
+- [ ] Note the original content for later verification
+
+---

forge/_extensions/skills/qa/resources/checklist/10-resume.md

@@ -0,0 +1,143 @@
+<!-- prereq: 0.3, 2.1, 5.1 -->
+
+## 10. Session Resume (Phase 10 Feature)
+
+### 10.1 Create Parent Session Artifacts
+
+<!-- auto -->
+
+```bash
+# Create a mock transcript artifact for testing resume
+SESSION_JSON=".forge/sessions/test-session-1/forge.session.json"
+SESSION_ID=$(jq -r '.confirmed.claude_session_id // "fixture-transcript"' "$SESSION_JSON")
+TRANSCRIPT_REL=".forge/artifacts/test-session-1/transcripts/${SESSION_ID}.jsonl"
+TRANSCRIPT_ABS="$FORGE_TEST_REPO/${TRANSCRIPT_REL}"
+
+mkdir -p "$(dirname "$TRANSCRIPT_ABS")"
+cat > "$TRANSCRIPT_ABS" << 'EOF'
+{"requestId":"req-1","timestamp":"2026-03-16T00:00:00Z","message":{"role":"user","content":[{"type":"text","text":"Create a hello world function"}]}}
+{"requestId":"req-1","timestamp":"2026-03-16T00:00:01Z","message":{"role":"assistant","content":[{"type":"text","text":"I'll create a simple hello world function for you."},{"type":"tool_use","id":"tool-1","name":"Write","input":{"file_path":"src/hello.py","content":"def hello():\n    return 'Hello, World!'"}}]}}
+{"requestId":"req-1","timestamp":"2026-03-16T00:00:02Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"tool-1","content":"File written successfully"}]}}
+{"requestId":"req-2","timestamp":"2026-03-16T00:00:03Z","message":{"role":"user","content":[{"type":"text","text":"Now add a test"}]}}
+{"requestId":"req-2","timestamp":"2026-03-16T00:00:04Z","message":{"role":"assistant","content":[{"type":"text","text":"I'll add a test for the hello function."},{"type":"tool_use","id":"tool-2","name":"Write","input":{"file_path":"tests/test_hello.py","content":"from src.hello import hello\n\ndef test_hello():\n    assert hello() == 'Hello, World!'"}}]}}
+{"requestId":"req-2","timestamp":"2026-03-16T00:00:05Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"tool-2","content":"File written successfully"}]}}
+EOF
+
+# Update session file with a realistic transcript artifact entry
+jq \
+  --arg transcript_abs "$TRANSCRIPT_ABS" \
+  --arg transcript_rel "$TRANSCRIPT_REL" \
+  --arg session_id "$SESSION_ID" \
+  '
+  .confirmed.transcript_path = $transcript_abs
+  | .confirmed.artifacts = ((.confirmed.artifacts // {}) + {
+      transcripts: [{
+        captured_at: "2026-03-16T00:00:00Z",
+        reason: "stop",
+        source_path: $transcript_abs,
+        session_id: $session_id,
+        copied_path: $transcript_rel,
+        copied: true
+      }]
+    })
+  ' "$SESSION_JSON" > /tmp/session.json && mv /tmp/session.json "$SESSION_JSON"
+```
+
+- [ ] Transcript artifact created under `.forge/artifacts/test-session-1/transcripts/`
+- [ ] Session file updated with transcript path and `confirmed.artifacts.transcripts[]`
+
+### 10.2 Resume with Minimal Strategy
+
+<!-- prereq: 10.1 -->
+
+<!-- requires: api_key -->
+
+<!-- human:guided -->
+
+In the **container shell**, resume with `--strategy minimal`. Claude will launch — verify the new session was created,
+then exit.
+
+```
+# Resume with minimal strategy (just lineage pointer)
+forge session resume test-session-1 --fresh --strategy minimal --child-name test-resumed-minimal
+
+# Check derived session
+cat .forge/sessions/test-resumed-minimal/forge.session.json | jq '.confirmed.derivation'
+```
+
+- [ ] New session created
+- [ ] Derivation shows parent, strategy, and transcript artifact path
+
+### 10.3 Resume with Structured Strategy
+
+<!-- prereq: 10.1 -->
+
+<!-- requires: api_key -->
+
+<!-- human:guided -->
+
+In the **container shell**, resume with `--strategy structured`. Claude will launch — verify the handoff file was
+created, then exit.
+
+```
+# Resume with structured strategy (conversation skeleton)
+forge session resume test-session-1 --fresh --strategy structured --child-name test-resumed-structured
+
+# Check processed handoff
+cat .forge/prev_sessions/test-session-1/generated.md
+```
+
+- [ ] Handoff file created at `.forge/prev_sessions/<parent>/children/<child>.md`
+- [ ] Contains conversation skeleton with truncated tool results
+
+### 10.4 Resume with Full Strategy
+
+<!-- prereq: 10.1 -->
+
+<!-- requires: api_key -->
+
+<!-- human:guided -->
+
+In the **container shell**, resume with `--strategy full`. This includes the complete transcript — the budget check may
+fail if the transcript is too large for the proxy context window.
+
+```
+# Resume with full strategy (complete transcript)
+forge session resume test-session-1 --fresh --strategy full --child-name test-resumed-full
+
+# Check the handoff
+cat .forge/prev_sessions/test-session-1/generated.md
+```
+
+- [ ] Full transcript included
+- [ ] Budget check passed (or error if too large)
+
+### 10.5 Resume with AI-Curated Strategy
+
+<!-- prereq: 10.1 -->
+
+<!-- requires: api_key -->
+
+<!-- human:guided -->
+
+In the **container shell**, resume with `--strategy ai-curated`. This uses OpenRouter directly to select highlights from
+the parent transcript, then launches the child session. Expect a security warning about external API access.
+
+```
+# Resume with AI-curated strategy (LLM-selected highlights)
+# NOTE: Requires OPENROUTER_API_KEY in the default QA provider profile.
+forge session delete test-resumed-ai --yes --force 2>/dev/null || true
+forge session resume test-session-1 --fresh --strategy ai-curated --child-name test-resumed-ai
+
+# Check the curated output or fallback output
+cat .forge/prev_sessions/test-session-1/generated.md
+```
+
+- [ ] Parent transcript fixture from 10.1 exists
+- [ ] Security warning shown about sending transcript content to OpenRouter
+- [ ] Default OpenRouter QA profile: handoff shows `Strategy: ai-curated` and LLM-selected highlights
+- [ ] If OpenRouter auth is unavailable, fallback to structured is acceptable and the warning explains the auth failure
+- [ ] No warning about missing remote LiteLLM infrastructure in the default OpenRouter QA profile
+- [ ] No `No transcript available; using minimal strategy` warning
+
+---

forge/_extensions/skills/qa/resources/checklist/11-config.md

@@ -0,0 +1,150 @@
+<!-- prereq: 0.3 -->
+
+## 11. Runtime Config + Claude Preset (`forge config`, `forge claude preset`)
+
+### 11.1 Initialize Config
+
+<!-- auto -->
+
+```bash
+# Config auto-creates with commented defaults on first access
+forge config show
+
+# Verify file created
+cat ${FORGE_HOME:-$HOME/.forge}/config.yaml
+```
+
+- [ ] Config file created at `${FORGE_HOME:-$HOME/.forge}/config.yaml`
+- [ ] Shows commented defaults (proxy_mode, sidecar_image, etc.)
+
+### 11.2 Show Effective Config
+
+<!-- auto -->
+
+```bash
+forge config show
+```
+
+- [ ] Shows all settings with current values
+- [ ] Shows defaults when no overrides set
+
+### 11.3 Set and Reset Values
+
+<!-- auto -->
+
+```bash
+# Set a value
+forge config set status_timeout=1.0
+
+# Switch proxy mode default (host vs sidecar)
+forge config set proxy_mode=sidecar
+
+# Verify
+forge config show | grep status_timeout
+forge config show | grep proxy_mode
+
+# Reset one key
+forge config reset status_timeout
+
+# Reset all
+forge config reset
+```
+
+- [ ] `set` persists the value
+- [ ] `reset` restores default
+- [ ] Type validation works (rejects invalid values)
+
+### 11.4 Edit in Editor
+
+<!-- human:guided -->
+
+In the **container shell**, run `forge config edit`. Verify `$EDITOR` opens `${FORGE_HOME:-$HOME/.forge}/config.yaml`.
+
+```
+forge config edit
+```
+
+- [ ] Opens `${FORGE_HOME:-$HOME/.forge}/config.yaml` in `$EDITOR`
+
+### 11.5 Show Claude Preset
+
+<!-- auto -->
+
+```bash
+# Show current preset (raw JSON auto-creates on first access)
+forge claude preset show --raw
+
+# Verify file created and built-in keys present
+python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+forge_home = Path(os.environ.get("FORGE_HOME", str(Path.home() / ".forge")))
+path = forge_home / "claude.preset.json"
+data = json.loads(path.read_text())
+has_hooks = "hooks" in data
+has_statusline = "statusLine" in data
+print("PRESET_PATH=" + str(path))
+print("HAS_HOOKS=" + str(has_hooks))
+print("HAS_STATUSLINE=" + str(has_statusline))
+PY
+```
+
+- [ ] Preset file created at `${FORGE_HOME:-$HOME/.forge}/claude.preset.json`
+- [ ] Built-in preset includes `hooks` and `statusLine`
+
+### 11.6 Reset Claude Preset
+
+<!-- auto -->
+
+```bash
+# Add a disposable custom env var to the preset
+python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+forge_home = Path(os.environ.get("FORGE_HOME", str(Path.home() / ".forge")))
+path = forge_home / "claude.preset.json"
+data = json.loads(path.read_text())
+data.setdefault("env", {})["QA_TEMP_PRESET"] = "1"
+path.write_text(json.dumps(data, indent=2) + "\n")
+print("ADDED_QA_TEMP_PRESET=1")
+PY
+
+# Reset to built-in defaults without prompting
+forge claude preset reset --force
+
+# Verify temporary key removed and built-in env preserved
+python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+forge_home = Path(os.environ.get("FORGE_HOME", str(Path.home() / ".forge")))
+path = forge_home / "claude.preset.json"
+data = json.loads(path.read_text())
+env = data.get("env", {})
+has_qa_temp_preset = "QA_TEMP_PRESET" in env
+print("HAS_QA_TEMP_PRESET=" + str(has_qa_temp_preset))
+PY
+```
+
+- [ ] `reset --force` restores the built-in preset non-interactively
+- [ ] Custom preset additions are removed while built-in values remain
+
+### 11.7 Edit Claude Preset in Editor
+
+<!-- human:guided -->
+
+In the **container shell**, run `forge claude preset edit`. Verify `$EDITOR` opens
+`${FORGE_HOME:-$HOME/.forge}/claude.preset.json`.
+
+```
+forge claude preset edit
+```
+
+- [ ] Opens `${FORGE_HOME:-$HOME/.forge}/claude.preset.json` in `$EDITOR`
+
+---

forge/_extensions/skills/qa/resources/checklist/12-search.md

@@ -0,0 +1,58 @@
+<!-- prereq: 0.3, 10.1 -->
+
+## 12. Search (`forge search`)
+
+### 12.1 Check Index Status
+
+<!-- auto -->
+
+```bash
+forge search status
+```
+
+- [ ] Shows index statistics (document count, store health)
+- [ ] Shows index location
+
+### 12.2 Build/Rebuild Index
+
+<!-- auto -->
+
+```bash
+# Full rebuild from all transcript artifacts
+forge search rebuild-index
+```
+
+- [ ] Rebuilds index from `.forge/artifacts/`
+- [ ] Reports number of documents indexed
+
+### 12.3 Search Transcripts
+
+<!-- auto -->
+
+```bash
+# Search for a keyword
+forge search -q "hello world"
+
+# Limit results
+forge search -q "test" -n 3
+
+# Search all projects
+forge search -q "hello world" --scope all
+```
+
+- [ ] Returns JSON results with session_name, score, snippet
+- [ ] `--scope all` searches indexed projects (including the current project)
+- [ ] Results ranked by BM25 relevance
+
+### 12.4 Clean Orphaned Entries
+
+<!-- auto -->
+
+```bash
+forge search clean
+```
+
+- [ ] Removes entries for deleted transcripts
+- [ ] Reports removed/pruned count or "No orphaned entries found."
+
+---

forge/_extensions/skills/qa/resources/checklist/13-guard.md

@@ -0,0 +1,237 @@
+<!-- prereq: 0.3, 5.1 -->
+
+## 13. Policy/Guard (`forge guard`)
+
+### 13.1 Guard Status
+
+<!-- auto -->
+
+```bash
+forge guard status
+```
+
+- [ ] Shows enabled/disabled state
+- [ ] Shows active bundles (if any)
+- [ ] Shows fail mode (if guard was previously enabled; omitted when never configured)
+
+### 13.2 Enable TDD Enforcement
+
+<!-- auto -->
+
+```bash
+# Enable TDD bundle
+forge guard enable --bundle tdd
+
+# Verify
+forge guard status
+```
+
+- [ ] TDD bundle activated
+- [ ] `tests-before-impl` and `no-skip-tests` rules listed
+
+### 13.3 Enable with Permissive Mode
+
+<!-- auto -->
+
+```bash
+# Enable TDD in warn-only mode
+forge guard enable --bundle tdd --permissive
+
+# Verify
+forge guard status
+```
+
+- [ ] TDD in permissive mode (warns instead of blocks)
+
+### 13.4 Enable Coding Standards
+
+<!-- auto -->
+
+```bash
+forge guard enable --bundle coding_standards
+
+forge guard status
+```
+
+- [ ] Coding standards bundle activated
+- [ ] `no-type-checking` and `no-backward-compat` rules listed
+
+### 13.5 On-Demand Policy Check
+
+<!-- auto -->
+
+```bash
+# Create a second commit so HEAD~1 is valid
+echo 'print("new")' >> src/main.py
+git add -A && git commit -q -m "add code for guard diff test"
+
+# Check a diff against policies
+git diff HEAD~1 | forge guard check --bundle tdd --bundle coding_standards --diff
+
+# Check with JSON output
+git diff HEAD~1 | forge guard check --bundle tdd --diff --json
+```
+
+- [ ] Evaluates diff against specified bundles
+- [ ] `--json` produces structured output with `passed` and `clean` fields
+
+### 13.6 Supervisor CLI Surface (Phase 19)
+
+<!-- auto -->
+
+```bash
+# Verify CLI is wired up
+forge guard supervisor --help
+
+# Missing file produces clear error (exit 2)
+forge guard supervisor -f /nonexistent/file.py -r 00000000-0000-0000-0000-000000000000 --json
+echo "exit: $?"
+```
+
+- [ ] `--help` shows usage with `-f`, `-r`, `--json`, `--proxy`, `--timeout` options
+- [ ] Missing file produces clear error and exit 2
+
+### 13.7 Manual Supervisor Wiring (Planner -> Supervisor -> Executor)
+
+<!-- prereq: 2.4, 4.2 -->
+
+<!-- requires: api_key -->
+
+<!-- human:guided -->
+
+This is a hands-on live-Claude smoke test. Do the phases in order. The terminal commands are copy/paste blocks for the
+container shell; the prompt blocks are for the Claude session that opens after each `forge session ...` command. If live
+Claude launch is unavailable in this environment, mark this step `Skip` rather than inventing evidence.
+
+**Phase 1: create an approved planner session**
+
+```bash
+cd $FORGE_TEST_REPO
+
+forge session delete guard-planner --force 2>/dev/null || true
+forge session delete guard-supervisor --force 2>/dev/null || true
+forge session delete guard-executor --force 2>/dev/null || true
+rm -f src/supervisor_demo.py
+
+forge session start guard-planner --proxy "$FORGE_QA_OPENAI_PROXY"
+```
+
+In Claude, type:
+
+```text
+/plan
+```
+
+Then paste:
+
+```text
+Skip the exploration step. Create a plan only. Do not edit files or run any write tools.
+
+The exact approved plan should be:
+1. Create `src/supervisor_demo.py`
+2. Add:
+   def greet(name: str) -> str:
+       return f"hello, {name}"
+3. Do not modify any other files
+
+After showing the plan, wait for my approval.
+```
+
+When Claude shows the plan, paste:
+
+```text
+I approve this exact plan. Do not implement it in this session. Wait.
+```
+
+Then exit Claude:
+
+```text
+/exit
+```
+
+Back in the container shell, verify that Claude wrote a plan file:
+
+```bash
+ls ~/.claude/plans/
+```
+
+**Phase 2: promote a dedicated supervisor session**
+
+```bash
+cd $FORGE_TEST_REPO
+
+forge session fork guard-planner --name guard-supervisor --no-launch
+forge session resume guard-supervisor
+```
+
+In Claude, paste:
+
+```text
+Reply with this exact phrase: supervisor ready
+```
+
+Then exit:
+
+```text
+/exit
+```
+
+**Phase 3: fork a direct executor and wire the supervisor**
+
+```bash
+cd $FORGE_TEST_REPO
+
+forge session fork guard-planner --name guard-executor --no-proxy --no-launch
+forge guard supervise guard-supervisor --session guard-executor --supervisor-proxy "$FORGE_QA_OPENAI_PROXY"
+FORGE_SESSION=guard-executor forge guard status
+forge session resume guard-executor
+```
+
+In Claude, paste:
+
+```text
+Create the file `src/supervisor_demo.py` with exactly this content:
+
+def greet(name: str) -> str:
+    return f"hello, {name}"
+
+Do not modify any other files. Do not add tests, docstrings, or imports.
+```
+
+After Claude finishes, exit:
+
+```text
+/exit
+```
+
+**Phase 4: inspect the result and run the one-shot supervisor check**
+
+```bash
+cd $FORGE_TEST_REPO
+
+cat src/supervisor_demo.py
+forge guard supervisor -f src/supervisor_demo.py -r guard-supervisor --json
+echo "exit: $?"
+```
+
+- [ ] Planner and supervisor sessions launch successfully; the planner has an approved plan and the supervisor session
+  materializes with a confirmed Claude session
+- [ ] Executor forks planner with `--no-proxy`, `forge guard supervise` wires `guard-supervisor`, `forge guard status`
+  shows `Supervisor: Configured`, and the executor implements the exact tiny planned file
+- [ ] `forge guard supervisor -f src/supervisor_demo.py -r guard-supervisor --json` returns structured output for the
+  real tiny task (expected: aligned / exit 0)
+
+### 13.8 Disable Policies
+
+<!-- auto -->
+
+```bash
+forge guard disable
+
+forge guard status
+```
+
+- [ ] All policies disabled
+- [ ] Status confirms disabled state
+
+---