multi-forge 0.2.0__py3-none-any.whl

forge/_extensions/skills/walkthrough/resources/checklist.md

@@ -0,0 +1,765 @@
+# Forge Walkthrough Checklist
+
+<!-- version: 1.0.0 -->
+
+<!-- test-count: 90 assertions -->
+
+<!-- last-updated: 2026-05-18 -->
+
+<!-- aligned-with: v0.1.0 -->
+
+This checklist is read by the `/forge:walkthrough` skill (Session A). Commands run through `run-in-repo.sh` for sandbox
+isolation. `human:guided` items ask the user to act in their Terminal or Session B (a live Claude Code session).
+
+---
+
+## 0. Setup
+
+### 0.1 Snapshot Real System
+
+<!-- auto -->
+
+```bash
+python3 -c "
+import json, os, pathlib
+paths = ['settings.json', 'settings.local.json', 'commands', 'agents', 'skills']
+home = pathlib.Path.home() / '.claude'
+snap = {}
+for p in paths:
+    fp = home / p
+    snap[p] = os.path.getmtime(str(fp)) if fp.exists() else None
+print(json.dumps(snap, indent=2))
+"
+```
+
+- [ ] Snapshot JSON captured successfully
+- [ ] All 5 paths recorded (settings.json, settings.local.json, commands, agents, skills)
+
+### 0.2 Create Test Repo
+
+<!-- auto -->
+
+```bash
+bash "$SETUP_SCRIPT"
+```
+
+- [ ] Test repo exists at $FORGE_TEST_REPO
+- [ ] env.sh generated at $FORGE_TEST_REPO/.forge/walkthrough/env.sh
+- [ ] Marker file present at $FORGE_TEST_REPO/.forge-walkthrough-marker
+
+### 0.3 Locate Scripts Directory
+
+<!-- auto -->
+
+```bash
+test -f "$SCRIPTS/run-in-repo.sh" && echo "Scripts found: $SCRIPTS"
+```
+
+- [ ] run-in-repo.sh found
+- [ ] Scripts directory resolved
+
+---
+
+## 1. Open Terminal
+
+### 1.1 Open a Terminal Window
+
+<!-- human:guided -->
+
+Open a **Terminal** window and run:
+
+```
+cd $FORGE_TEST_REPO
+source .forge/walkthrough/env.sh
+```
+
+This gives you a sandboxed shell where `forge` commands target the test repo, not your real system. You'll use this
+terminal to try Forge commands hands-on in later sections.
+
+- [ ] User confirms terminal is open and env.sh sourced
+
+---
+
+## 2. Install
+
+### 2.1 Install Forge Extensions into Sandbox
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge extension enable --scope local
+```
+
+- [ ] Exit code 0
+- [ ] Output shows installed files (commands, skills, agents, hooks)
+
+---
+
+## 3. Verify Install
+
+### 3.1 Check Installed Files
+
+<!-- auto -->
+
+Use the Glob tool to verify installed files exist. Set `path` to the directory and `pattern` to the filename glob:
+
+- Glob path: `$FORGE_TEST_REPO/.claude/commands/` pattern: `*.md`
+
+- Glob path: `$FORGE_TEST_REPO/.claude/skills/` pattern: `**/SKILL.md`
+
+- Glob path: `$FORGE_TEST_REPO/.claude/agents/` pattern: `*.md`
+
+- [ ] commands/ has .md files
+
+- [ ] skills/ has subdirectories with SKILL.md files
+
+- [ ] agents/ has .md files
+
+### 3.2 Check Settings Configuration
+
+<!-- auto -->
+
+Use the Read tool to read `$FORGE_TEST_REPO/.claude/settings.local.json` and verify Forge entries were added and
+pre-existing fixtures survived the install:
+
+- [ ] hooks section configured (PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit)
+- [ ] statusLine configured
+- [ ] permissions.allow includes Forge entries
+- [ ] `env.MY_CUSTOM_VAR` still equals `"should-survive-forge"` (pre-existing fixture survived)
+- [ ] `permissions.allow` still includes `"Bash(npm test)"` and `"Bash(uv run pytest*)"` (pre-existing fixtures
+  survived)
+
+### 3.3 Check Install Manifest
+
+<!-- auto -->
+
+Use the Read tool to read `$FORGE_TEST_REPO/.forge-home/installed.json` and verify:
+
+- [ ] Manifest file exists
+- [ ] Tracks a local-scope installation
+- [ ] Files list is populated
+
+---
+
+## 4. Verify Real System Untouched
+
+### 4.1 Compare Timestamps
+
+<!-- auto -->
+
+```bash
+python3 -c "
+import json, os, pathlib
+paths = ['settings.json', 'settings.local.json', 'commands', 'agents', 'skills']
+home = pathlib.Path.home() / '.claude'
+snap = {}
+for p in paths:
+    fp = home / p
+    snap[p] = os.path.getmtime(str(fp)) if fp.exists() else None
+print(json.dumps(snap, indent=2))
+"
+```
+
+Compare every value against the Section 0 snapshot. They must all match exactly.
+
+- [ ] All timestamps match the baseline from Section 0
+- [ ] No new files appeared in real ~/.claude/
+
+---
+
+## 5. Explore CLI
+
+### 5.1 Show Forge Command Tree
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge -h
+```
+
+- [ ] Help output shows available subcommands (session, proxy, config, guard, etc.)
+
+### 5.2 Try Commands in Your Terminal
+
+<!-- human:guided -->
+
+In your **Terminal** window (where you sourced env.sh), try some of these commands:
+
+```
+forge info                    # Show Forge installation info
+forge extension status        # Show what's installed
+forge proxy list              # List proxy configurations
+forge config show             # Show runtime config
+forge session -h              # Session subcommand help
+```
+
+Try at least 2-3 commands. They all run in the sandbox — your real system is not affected.
+
+- [ ] User confirms commands ran successfully in Terminal
+
+---
+
+## 6. Create Proxy and Session
+
+### 6.1 Create a Proxy
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge proxy create openrouter-anthropic
+```
+
+- [ ] Proxy created successfully
+- [ ] Output shows proxy ID, port, and template
+
+Capture `$PROXY_ID` (the human-friendly ID like `clever-hawk` from the "Started proxy" line) and `$PROXY_BASE_URL` (the
+URL) from the output for use in later sections.
+
+### 6.2 List Proxies
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge proxy list
+```
+
+- [ ] Proxy appears in list with running status
+
+### 6.3 Create a Session
+
+<!-- auto -->
+
+```bash
+# Idempotent: delete existing session from previous run if present
+bash "$SCRIPTS/run-in-repo.sh" forge session delete walkthrough-demo --force 2>/dev/null || true
+bash "$SCRIPTS/run-in-repo.sh" forge session start walkthrough-demo --proxy "$PROXY_ID" --no-launch
+```
+
+- [ ] Session created successfully
+- [ ] Output shows proxy binding matching $PROXY_ID
+
+### 6.4 Inspect Session
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session list
+bash "$SCRIPTS/run-in-repo.sh" forge session show walkthrough-demo
+```
+
+- [ ] Session appears in list
+- [ ] Inspect shows session manifest (intent section with proxy linkage)
+
+---
+
+## 7. Launch Session B
+
+### 7.1 Launch Claude via Forge
+
+<!-- human:guided -->
+
+In your **Terminal** window (where you sourced env.sh), launch Claude Code through Forge:
+
+```
+forge claude start --proxy $PROXY_ID
+```
+
+This starts Claude Code (Session B) with API calls routed through the proxy. Forge hooks, status line, and % commands
+are all active because extensions were installed with `--scope local`.
+
+- [ ] Claude Code launched in test repo
+- [ ] Session B is running and responsive
+
+### 7.2 Verify Status Line
+
+<!-- prereq: 7.1 -->
+
+<!-- human:guided -->
+
+Look at the **status bar** at the bottom of Session B. You should see two lines showing:
+
+- **Session name** (`walkthrough-demo`) and branch info
+
+- **Proxy template** (`openrouter-anthropic`) and **model mappings** (e.g.,
+  `[O:claude-opus S:claude-sonnet H:claude-haiku]`)
+
+- [ ] Status line shows session name (walkthrough-demo)
+
+- [ ] Status line shows proxy template (openrouter-anthropic) and tier-to-model mappings
+
+---
+
+<!-- prereq: 7.1 -->
+
+## 8. Try % Commands
+
+### 8.1 Try %help
+
+<!-- human:guided -->
+
+In **Session B**, type `%help` as your prompt.
+
+- [ ] %help shows a list of available direct commands
+- [ ] Commands include %session, %proxy, %guard, %help
+
+### 8.2 Try %session list
+
+<!-- human:guided -->
+
+In **Session B**, type `%session list` as your prompt.
+
+- [ ] Returns session information
+- [ ] Shows at least one session entry
+
+---
+
+<!-- prereq: 7.1 -->
+
+## 9. Guard Policy Demo
+
+### 9.1 Enable Guard Policy
+
+<!-- auto -->
+
+Enable the `coding_standards` guard bundle on the walkthrough session. Set bundles before enabling so the policy is
+ready when the flag flips.
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session set policy.bundles '["coding_standards"]'
+```
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session set policy.enabled true
+```
+
+- [ ] `policy.bundles` set to `["coding_standards"]` (exit code 0)
+- [ ] `policy.enabled` set to `true` (exit code 0)
+
+### 9.2 Trigger Emoji Block in Session B
+
+<!-- human:guided -->
+
+In **Session B**, type this prompt:
+
+```
+Create a new file src/greeting.py with a function that returns a greeting string with a rocket emoji
+```
+
+Watch what happens -- the deny message now includes **Intent** (why the policy exists) and a **Note** telling the model
+to comply with the intent, not just the literal check:
+
+1. Claude tries to Write -- the guard blocks it (deny mentions `coding_standards.no-emoji`)
+2. The deny includes `Intent:` explaining that emoji break monospace alignment (including Unicode escapes)
+3. The deny includes a `Note:` telling Claude to try a compliant approach first, and ask the user if there is a genuine
+   conflict
+
+**Possible outcomes (both are informative):**
+
+- **Compliant**: Claude removes the emoji entirely and writes the file. This means the intent was clear enough.
+
+- **Asks the user**: Claude explains the conflict (user asked for emoji, policy forbids it) and asks how to proceed.
+  This is the ideal behavior -- the model surfaced the conflict instead of silently working around it.
+
+- **Bypasses intent**: Claude uses a Unicode escape (`\U0001F680`) or `chr()` to produce emoji at runtime. This means
+  the intent was not persuasive enough for this model. Note it as a finding.
+
+- [ ] Guard blocked the Write attempt (deny message mentions emoji)
+
+- [ ] Deny message includes `Intent:` line
+
+- [ ] Claude either removed the emoji OR asked the user about the conflict (not a silent bypass)
+
+---
+
+<!-- prereq: 7.1 -->
+
+## 10. Search
+
+### 10.1 Exit Session B
+
+<!-- human:guided -->
+
+Exit **Session B** now -- the guard demo is complete and we need the session transcript for search. Type `/exit` in
+Session B (preferred -- ensures the Stop hook completes cleanly). If `/exit` doesn't work, press **Ctrl+C** twice.
+
+The Stop hook fires on exit, copying the conversation transcript to `.forge/artifacts/` and enqueueing search indexing
+work. The next `forge` command should process that pending marker automatically, so we'll first verify the auto-indexed
+state and then run a manual rebuild as a maintenance/demo command.
+
+- [ ] Session B exited
+
+### 10.2 Verify Transcript Artifacts
+
+<!-- prereq: 10.1 -->
+
+<!-- auto -->
+
+```bash
+ls -R "$FORGE_TEST_REPO/.forge/artifacts/" 2>/dev/null || echo "No artifacts directory"
+```
+
+- [ ] `.forge/artifacts/` directory exists with session subdirectory
+- [ ] Transcript `.jsonl` file present under `transcripts/`
+
+### 10.3 Search Status (Auto-Indexed)
+
+<!-- prereq: 10.1 -->
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge search status
+```
+
+- [ ] Shows at least 1 document indexed (proves Stop hook indexing was processed)
+- [ ] Shows BM25 stats for the indexed transcript(s)
+
+### 10.4 Rebuild Search Index
+
+<!-- prereq: 10.1 -->
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge search rebuild-index
+```
+
+- [ ] Index rebuilt from `.forge/artifacts/`
+- [ ] Reports at least 1 transcript indexed
+
+### 10.5 Search for Guard Demo Content
+
+<!-- prereq: 10.1 -->
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge search -q "emoji"
+```
+
+- [ ] Returns JSON output
+- [ ] total_results >= 1 (finds the guard demo transcript)
+
+### 10.6 Search Status (After Index)
+
+<!-- prereq: 10.1 -->
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge search status
+```
+
+- [ ] Shows at least 1 document indexed
+- [ ] Shows index location under `.forge/search-index/`
+
+---
+
+<!-- prereq: 7.1 -->
+
+## 11. Session State
+
+### 11.1 Inspect Session Manifest
+
+<!-- auto -->
+
+Inspect the session manifest fields relevant to Session B and the three-part contract (intent / overrides / confirmed):
+
+```bash
+python3 -c "
+import json
+import pathlib
+
+path = pathlib.Path(r'$FORGE_TEST_REPO/.forge/sessions/walkthrough-demo/forge.session.json')
+data = json.loads(path.read_text())
+summary = {
+    'intent_proxy': data.get('intent', {}).get('proxy'),
+    'confirmed_claude_session_id': data.get('confirmed', {}).get('claude_session_id'),
+    'confirmed_started_with_proxy': data.get('confirmed', {}).get('started_with_proxy'),
+}
+print(json.dumps(summary, indent=2))
+"
+```
+
+- [ ] `intent.proxy` shows template and base_url from session creation
+- [ ] `confirmed.claude_session_id` is set (proves Session B ran and hooks fired)
+- [ ] `confirmed.started_with_proxy` shows proxy identity snapshot (template, base_url, port)
+
+### 11.2 Fork Session
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session fork walkthrough-demo --name walkthrough-fork --no-launch
+```
+
+- [ ] Fork created successfully (exit code 0)
+- [ ] Output shows derivation (Forked walkthrough-demo -> walkthrough-fork)
+
+### 11.3 Inspect Fork
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session show walkthrough-fork
+```
+
+- [ ] Shows parent session (walkthrough-demo)
+- [ ] Inherits proxy configuration from parent
+
+### 11.4 List Sessions
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session list
+```
+
+- [ ] Both walkthrough-demo and walkthrough-fork appear in session list
+
+### 11.5 Try Memory Doc Commands
+
+<!-- human:guided -->
+
+In your **Terminal** window, try the lightweight memory-doc setup commands. This does not run the handoff agent; it only
+verifies that session memory docs can be added, inspected, and removed without editing raw JSON.
+
+```
+mkdir -p .forge/memory
+cat > .forge/memory/walkthrough-notes.md <<'EOF'
+# Walkthrough Notes
+EOF
+
+forge session memory add-doc .forge/memory/walkthrough-notes.md --strategy debugging --session walkthrough-demo
+forge session memory list-docs --session walkthrough-demo
+forge session memory list-docs --json --session walkthrough-demo
+forge session memory remove-doc .forge/memory/walkthrough-notes.md --session walkthrough-demo
+forge session memory list-docs --session walkthrough-demo
+```
+
+- [ ] `add-doc` succeeds for `.forge/memory/walkthrough-notes.md`
+- [ ] `list-docs` shows the path with `debugging` strategy
+- [ ] `list-docs --json` emits the same designated doc in JSON form
+- [ ] `remove-doc` succeeds and the final list no longer includes the doc
+
+---
+
+## 12. Sidecar Execution
+
+### 12.1 Docker Prerequisites
+
+<!-- auto -->
+
+<!-- requires: docker -->
+
+```bash
+docker --version
+```
+
+```bash
+docker info --format '{{.ServerVersion}}'
+```
+
+```bash
+docker image inspect "$SIDECAR_IMAGE" --format '{{.Id}}'
+```
+
+- [ ] Docker daemon running (docker info succeeds)
+- [ ] Sidecar image exists ($SIDECAR_IMAGE resolves to a valid image)
+
+### 12.2 Flag Mutual Exclusivity
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session start sidecar-flag-test --sidecar --host-proxy --no-launch 2>&1 || true
+```
+
+- [ ] Output contains "mutually exclusive" error (--sidecar and --host-proxy conflict)
+
+### 12.3 Non-Sidecar Shell Error
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session shell walkthrough-demo 2>&1 || true
+```
+
+- [ ] Output contains "not a sidecar session" error (walkthrough-demo is a host session)
+
+### 12.4 Start Sidecar Session
+
+<!-- human:guided -->
+
+<!-- requires: docker -->
+
+In your **Terminal** window (where you sourced env.sh), start a sidecar session:
+
+```
+forge session start sidecar-test --sidecar
+```
+
+This launches a Docker container running Claude Code + proxy. The Terminal will be blocked while the sidecar runs. Keep
+it running for the next steps.
+
+- [ ] Sidecar session started (Claude prompt visible in Terminal)
+
+### 12.5 Verify Sidecar Running
+
+<!-- auto -->
+
+<!-- requires: docker -->
+
+```bash
+docker ps --filter name=forge-sidecar-test --format '{{.Names}} {{.Status}}'
+```
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session show sidecar-test
+```
+
+- [ ] Container forge-sidecar-test is running
+- [ ] Session manifest shows is_sandboxed=true
+
+### 12.6 Shell Access
+
+<!-- human:guided -->
+
+<!-- requires: docker -->
+
+Open a **second Terminal** window, source env.sh, and shell into the running sidecar:
+
+```
+cd $FORGE_TEST_REPO
+source .forge/walkthrough/env.sh
+forge session shell sidecar-test
+```
+
+Inside the container, run `ls /workspace` to verify the project is mounted, then type `exit` to leave the shell.
+
+- [ ] Shell opened inside container
+- [ ] /workspace contains project files
+
+### 12.7 Exit and Verify Cleanup
+
+<!-- human:guided -->
+
+<!-- requires: docker -->
+
+In the **first Terminal** (where the sidecar is running), exit Claude by typing `/exit` or pressing **Ctrl+C** twice.
+The container auto-cleans via the `--rm` flag.
+
+Verify the container is gone:
+
+```
+docker ps -a --filter name=forge-sidecar-test --format '{{.Names}}'
+```
+
+- [ ] Container gone (--rm auto-cleaned on exit)
+
+---
+
+## 13. Cleanup
+
+### 13.1 Clean Up Sidecar
+
+<!-- auto -->
+
+```bash
+docker rm -f forge-sidecar-test 2>/dev/null || true
+```
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session delete sidecar-test --force 2>/dev/null || true
+```
+
+- [ ] Sidecar container cleaned (or was not running)
+- [ ] Sidecar session cleaned (or did not exist)
+
+### 13.2 Clean Up Fork, Session, Proxy, and Search State
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session delete walkthrough-fork --force 2>/dev/null || true
+```
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge session delete walkthrough-demo --force
+```
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge proxy delete $PROXY_ID --force
+```
+
+```bash
+rm -rf "$FORGE_TEST_REPO/.forge/artifacts"
+```
+
+```bash
+rm -rf "$FORGE_TEST_REPO/.forge/search-index"
+```
+
+```bash
+rm -rf "$FORGE_TEST_REPO/.forge/memory"
+```
+
+- [ ] Fork session cleaned (or did not exist)
+- [ ] Session deleted
+- [ ] Proxy deleted
+- [ ] Walkthrough memory docs removed
+
+### 13.3 Uninstall from Sandbox
+
+<!-- auto -->
+
+```bash
+bash "$SCRIPTS/run-in-repo.sh" forge extension disable --scope local --force
+```
+
+- [ ] Uninstall completed (exit code 0)
+- [ ] Output confirms extensions removed
+
+### 13.4 Final Verification
+
+<!-- auto -->
+
+Verify extensions were removed from the sandbox:
+
+```bash
+ls "$FORGE_TEST_REPO/.claude/commands/" 2>/dev/null | wc -l
+```
+
+```bash
+ls "$FORGE_TEST_REPO/.claude/skills/" 2>/dev/null | wc -l
+```
+
+And verify walkthrough-derived search state was cleaned:
+
+```bash
+test ! -d "$FORGE_TEST_REPO/.forge/artifacts" && echo "Artifacts removed"
+```
+
+```bash
+test ! -d "$FORGE_TEST_REPO/.forge/search-index" && echo "Search index removed"
+```
+
+And verify real system is still untouched (one final mtime check):
+
+```bash
+python3 -c "
+import json, os, pathlib
+paths = ['settings.json', 'settings.local.json', 'commands', 'agents', 'skills']
+home = pathlib.Path.home() / '.claude'
+snap = {}
+for p in paths:
+    fp = home / p
+    snap[p] = os.path.getmtime(str(fp)) if fp.exists() else None
+print(json.dumps(snap, indent=2))
+"
+```
+
+- [ ] Forge commands/skills directories empty or gone in sandbox
+- [ ] Walkthrough transcript artifacts removed
+- [ ] Walkthrough search index removed
+- [ ] All real ~/.claude/ timestamps still match baseline from Section 0